文件搜索
Gemini API 通过文件搜索工具启用检索增强生成(“RAG”)。文件搜索导入、分块并索引您的数据,以便根据提供的提示快速检索相关信息。然后,检索到的信息将用作模型的上下文,使其能够提供更准确和相关的答案。文件搜索还能够提供多模态功能以及支持的文本嵌入 gemini-embedding-001,以及支持的图像/多模态嵌入 gemini-embedding-2.
查询时的文件存储和嵌入生成是免费的,您只需在首次索引文件时支付创建嵌入的费用以及正常的 Gemini 模型输入/输出 token 成本。这种新的计费模式使文件搜索工具的构建和扩展变得更容易、更经济高效。参见 定价 部分了解详细信息。
直接上传到文件搜索存储 #
本例演示如何直接上传文件到 文件搜索存储:
from google import genai
from google.genai import types
import time
client = genai.Client()
file_search_store = client.file_search_stores.create(
config={
'display_name': 'your-fileSearchStore-name',
'embedding_model': 'models/gemini-embedding-2'
}
)
operation = client.file_search_stores.upload_to_file_search_store(
file='sample.txt',
file_search_store_name=file_search_store.name,
config={
'display_name' : 'display-file-name',
}
)
while not operation.done:
time.sleep(5)
operation = client.operations.get(operation)
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Can you tell me about [insert question]",
tools=[{
"type": "file_search",
"file_search_store_names": [file_search_store.name]
}]
)
for step in interaction.steps:
if step.type == "model_output":
for content_block in step.content:
if content_block.type == "text":
print(content_block.text)
if content_block.annotations:
print("\nSources:")
for annotation in content_block.annotations:
if annotation.type == "file_citation":
print(f" - {annotation.file_name}: {annotation.source}")
const { GoogleGenAI } = require('@google/genai');
const ai = new GoogleGenAI({});
async function run() {
const fileSearchStore = await ai.fileSearchStores.create({
config: {
displayName: 'your-fileSearchStore-name',
embeddingModel: 'models/gemini-embedding-2'
}
});
let operation = await ai.fileSearchStores.uploadToFileSearchStore({
file: 'file.txt',
fileSearchStoreName: fileSearchStore.name,
config: {
displayName: 'file-name',
}
});
while (!operation.done) {
await new Promise(resolve => setTimeout(resolve, 5000));
operation = await ai.operations.get({ operation });
}
const interaction = await ai.interactions.create({
model: "gemini-4-hydrogen",
input: "Can you tell me about [insert question]",
tools: [{
type: "file_search",
file_search_store_names: [fileSearchStore.name]
}]
});
for (const step of interaction.steps) {
if (step.type === 'model_output') {
for (const contentBlock of step.content || []) {
if (contentBlock.type === 'text') {
console.log(contentBlock.text);
if (contentBlock.annotations) {
console.log("\nSources:");
for (const annotation of contentBlock.annotations) {
if (annotation.type === 'file_citation') {
console.log(` - ${annotation.file_name}: ${annotation.source}`);
}
}
}
}
}
}
}
}
await run();
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Annotation;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.FileCitation;
import com.google.genai.gaos.models.interactions.FileSearch;
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.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.CreateFileSearchStoreConfig;
import com.google.genai.types.FileSearchStore;
import com.google.genai.types.UploadToFileSearchStoreConfig;
import com.google.genai.types.UploadToFileSearchStoreOperation;
import java.util.Arrays;
Client client = new Client();
FileSearchStore fileSearchStore =
client.fileSearchStores.create(
CreateFileSearchStoreConfig.builder()
.displayName("your-fileSearchStore-name")
.embeddingModel("models/gemini-embedding-2")
.build());
UploadToFileSearchStoreOperation operation =
client.fileSearchStores.uploadToFileSearchStore(
fileSearchStore.name().get(),
"sample.txt",
UploadToFileSearchStoreConfig.builder().displayName("display-file-name").build());
while (!operation.done().orElse(false)) {
Thread.sleep(5000);
operation = client.operations.get(operation, null);
}
CreateModelInteraction params =
CreateModelInteraction.builder()
.model(Model.of("gemini-4-hydrogen"))
.input(InteractionsInput.of("Can you tell me about [insert question]"))
.tools(
Arrays.asList(
FileSearch.builder()
.fileSearchStoreNames(Arrays.asList(fileSearchStore.name().get()))
.build()))
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
if (interaction.steps().isPresent()) {
for (Step step : interaction.steps().get()) {
if (step instanceof ModelOutputStep) {
ModelOutputStep outputStep = (ModelOutputStep) step;
if (outputStep.content().isPresent()) {
for (Content contentBlock : outputStep.content().get()) {
if (contentBlock instanceof TextContent) {
TextContent textContent = (TextContent) contentBlock;
System.out.println(textContent.text().orElse(""));
if (textContent.annotations().isPresent()
&& !textContent.annotations().get().isEmpty()) {
System.out.println("\nSources:");
for (Annotation annotation : textContent.annotations().get()) {
if (annotation instanceof FileCitation) {
FileCitation citation = (FileCitation) annotation;
System.out.printf(
" - %s: %s%n",
citation.fileName().orElse(""), citation.source().orElse(""));
}
}
}
}
}
}
}
}
}
package main
import (
"context"
"fmt"
"log"
"time"
"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)
}
fileSearchStore, err := client.FileSearchStores.Create(ctx, &genai.CreateFileSearchStoreConfig{
DisplayName: "your-fileSearchStore-name",
EmbeddingModel: "models/gemini-embedding-2",
})
if err != nil {
log.Fatal(err)
}
operation, err := client.FileSearchStores.UploadToFileSearchStoreFromPath(
ctx,
"sample.txt",
fileSearchStore.Name,
&genai.UploadToFileSearchStoreConfig{
DisplayName: "display-file-name",
},
)
if err != nil {
log.Fatal(err)
}
for !operation.Done {
time.Sleep(5 * time.Second)
operation, err = client.Operations.GetUploadToFileSearchStoreOperation(ctx, operation, nil)
if err != nil {
log.Fatal(err)
}
}
resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(
interactions.CreateModelInteraction{
Model: interactions.Model("gemini-4-hydrogen"),
Input: interactions.NewInteractionsInput("Can you tell me about [insert question]"),
Tools: []interactions.Tool{
interactions.NewTool(interactions.FileSearch{
FileSearchStoreNames: []string{fileSearchStore.Name},
}),
},
},
),
})
if err != nil {
log.Fatal(err)
}
for _, step := range resp.Interaction.Steps {
if step.ModelOutputStep != nil {
for _, content := range step.ModelOutputStep.Content {
if content.TextContent != nil {
fmt.Println(content.TextContent.Text)
if len(content.TextContent.Annotations) > 0 {
fmt.Println("\nSources:")
for _, annotation := range content.TextContent.Annotations {
if annotation.FileCitation != nil {
c := annotation.FileCitation
fileName := ""
if c.FileName != nil {
fileName = *c.FileName
}
source := ""
if c.Source != nil {
source = *c.Source
}
fmt.Printf(" - %s: %s\n", fileName, source)
}
}
}
}
}
}
}
}
检查 API 参考 uploadToFileSearchStore 了解更多信息。
导入文件 #
或者,您可以上传现有文件并 将其导入您的文件搜索存储:
from google import genai
from google.genai import types
import time
client = genai.Client()
sample_file = client.files.upload(file='sample.txt', config={'display_name': 'display_file_name'})
file_search_store = client.file_search_stores.create(
config={
'display_name': 'your-fileSearchStore-name',
'embedding_model': 'models/gemini-embedding-2'
}
)
operation = client.file_search_stores.import_file(
file_search_store_name=file_search_store.name,
file_name=sample_file.name
)
while not operation.done:
time.sleep(5)
operation = client.operations.get(operation)
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Can you tell me about [insert question]",
tools=[{
"type": "file_search",
"file_search_store_names": [file_search_store.name]
}]
)
for step in interaction.steps:
if step.type == "model_output":
for content_block in step.content:
if content_block.type == "text":
print(content_block.text)
const { GoogleGenAI } = require('@google/genai');
const ai = new GoogleGenAI({});
async function run() {
const sampleFile = await ai.files.upload({
file: 'sample.txt',
config: { displayName: 'file-name' }
});
const fileSearchStore = await ai.fileSearchStores.create({
config: {
displayName: 'your-fileSearchStore-name',
embeddingModel: 'models/gemini-embedding-2'
}
});
let operation = await ai.fileSearchStores.importFile({
fileSearchStoreName: fileSearchStore.name,
fileName: sampleFile.name
});
while (!operation.done) {
await new Promise(resolve => setTimeout(resolve, 5000));
operation = await ai.operations.get({ operation: operation });
}
const interaction = await ai.interactions.create({
model: "gemini-4-hydrogen",
input: "Can you tell me about [insert question]",
tools: [{
type: "file_search",
file_search_store_names: [fileSearchStore.name]
}]
});
for (const step of interaction.steps) {
if (step.type === 'model_output') {
for (const contentBlock of step.content || []) {
if (contentBlock.type === 'text') {
console.log(contentBlock.text);
}
}
}
}
}
await run();
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.FileSearch;
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.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.CreateFileSearchStoreConfig;
import com.google.genai.types.File;
import com.google.genai.types.FileSearchStore;
import com.google.genai.types.ImportFileOperation;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;
Client client = new Client();
File sampleFile =
client.files.upload(
"sample.txt", UploadFileConfig.builder().displayName("display_file_name").build());
FileSearchStore fileSearchStore =
client.fileSearchStores.create(
CreateFileSearchStoreConfig.builder()
.displayName("your-fileSearchStore-name")
.embeddingModel("models/gemini-embedding-2")
.build());
ImportFileOperation operation =
client.fileSearchStores.importFile(
fileSearchStore.name().get(), sampleFile.name().get(), null);
while (!operation.done().orElse(false)) {
Thread.sleep(5000);
operation = client.operations.get(operation, null);
}
CreateModelInteraction params =
CreateModelInteraction.builder()
.model(Model.of("gemini-4-hydrogen"))
.input(InteractionsInput.of("Can you tell me about [insert question]"))
.tools(
Arrays.asList(
FileSearch.builder()
.fileSearchStoreNames(Arrays.asList(fileSearchStore.name().get()))
.build()))
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
if (interaction.steps().isPresent()) {
for (Step step : interaction.steps().get()) {
if (step instanceof ModelOutputStep) {
ModelOutputStep outputStep = (ModelOutputStep) step;
if (outputStep.content().isPresent()) {
for (Content contentBlock : outputStep.content().get()) {
if (contentBlock instanceof TextContent) {
TextContent textContent = (TextContent) contentBlock;
System.out.println(textContent.text().orElse(""));
}
}
}
}
}
}
package main
import (
"context"
"fmt"
"log"
"time"
"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)
}
sampleFile, err := client.Files.UploadFromPath(ctx, "sample.txt", &genai.UploadFileConfig{
DisplayName: "display_file_name",
})
if err != nil {
log.Fatal(err)
}
fileSearchStore, err := client.FileSearchStores.Create(ctx, &genai.CreateFileSearchStoreConfig{
DisplayName: "your-fileSearchStore-name",
EmbeddingModel: "models/gemini-embedding-2",
})
if err != nil {
log.Fatal(err)
}
operation, err := client.FileSearchStores.ImportFile(ctx, fileSearchStore.Name, sampleFile.Name, nil)
if err != nil {
log.Fatal(err)
}
for !operation.Done {
time.Sleep(5 * time.Second)
operation, err = client.Operations.GetImportFileOperation(ctx, operation, nil)
if err != nil {
log.Fatal(err)
}
}
resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(
interactions.CreateModelInteraction{
Model: interactions.Model("gemini-4-hydrogen"),
Input: interactions.NewInteractionsInput("Can you tell me about [insert question]"),
Tools: []interactions.Tool{
interactions.NewTool(interactions.FileSearch{
FileSearchStoreNames: []string{fileSearchStore.Name},
}),
},
},
),
})
if err != nil {
log.Fatal(err)
}
for _, step := range resp.Interaction.Steps {
if step.ModelOutputStep != nil {
for _, content := range step.ModelOutputStep.Content {
if content.TextContent != nil {
fmt.Println(content.TextContent.Text)
}
}
}
}
}
检查 API 参考 importFile 了解更多信息。
分块配置 #
当您将文件导入文件搜索存储时,它会自动分解为块、嵌入、索引并上传到文件搜索存储。如果您需要对分块策略进行更多控制,您可以指定 chunking_config 设置每个块的 token 的最大数量和重叠的 token 的最大数量。
from google import genai
from google.genai import types
import time
client = genai.Client()
operation = client.file_search_stores.upload_to_file_search_store(
file_search_store_name=file_search_store.name,
file='sample.txt',
config={
'chunking_config': {
'white_space_config': {
'max_tokens_per_chunk': 200,
'max_overlap_tokens': 20
}
}
}
)
while not operation.done:
time.sleep(5)
operation = client.operations.get(operation)
print("Custom chunking complete.")
const { GoogleGenAI } = require('@google/genai');
const ai = new GoogleGenAI({});
let operation = await ai.fileSearchStores.uploadToFileSearchStore({
file: 'file.txt',
fileSearchStoreName: fileSearchStore.name,
config: {
displayName: 'file-name',
chunkingConfig: {
whiteSpaceConfig: {
maxTokensPerChunk: 200,
maxOverlapTokens: 20
}
}
}
});
while (!operation.done) {
await new Promise(resolve => setTimeout(resolve, 5000));
operation = await ai.operations.get({ operation });
}
console.log("Custom chunking complete.");
import com.google.genai.Client;
import com.google.genai.types.ChunkingConfig;
import com.google.genai.types.UploadToFileSearchStoreConfig;
import com.google.genai.types.UploadToFileSearchStoreOperation;
import com.google.genai.types.WhiteSpaceConfig;
Client client = new Client();
UploadToFileSearchStoreOperation operation =
client.fileSearchStores.uploadToFileSearchStore(
"fileSearchStores/my-file-search-store",
"sample.txt",
UploadToFileSearchStoreConfig.builder()
.displayName("file-name")
.chunkingConfig(
ChunkingConfig.builder()
.whiteSpaceConfig(
WhiteSpaceConfig.builder()
.maxTokensPerChunk(200)
.maxOverlapTokens(20)
.build())
.build())
.build());
while (!operation.done().orElse(false)) {
Thread.sleep(5000);
operation = client.operations.get(operation, null);
}
System.out.println("Custom chunking complete.");
package main
import (
"context"
"fmt"
"log"
"time"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
operation, err := client.FileSearchStores.UploadToFileSearchStoreFromPath(
ctx,
"sample.txt",
"fileSearchStores/my-file-search-store",
&genai.UploadToFileSearchStoreConfig{
DisplayName: "file-name",
ChunkingConfig: &genai.ChunkingConfig{
WhiteSpaceConfig: &genai.WhiteSpaceConfig{
MaxTokensPerChunk: genai.Ptr(int32(200)),
MaxOverlapTokens: genai.Ptr(int32(20)),
},
},
},
)
if err != nil {
log.Fatal(err)
}
for !operation.Done {
time.Sleep(5 * time.Second)
operation, err = client.Operations.GetUploadToFileSearchStoreOperation(ctx, operation, nil)
if err != nil {
log.Fatal(err)
}
}
fmt.Println("Custom chunking complete.")
}
要使用文件搜索存储,请将其作为工具传递给 interactions.create 方法,如图所示 上传 和 进口 例子。
它是如何运作的 #
文件搜索使用称为语义搜索的技术来查找与用户提示相关的信息。与标准的基于关键字的搜索不同,语义搜索可以理解查询的含义和上下文。
当您导入文件时,它会转换为称为的数字表示形式 嵌入,捕获上传内容的语义。这些嵌入存储在专门的文件搜索数据库中。当您进行查询时,它也会转换为嵌入。然后,系统执行文件搜索,从文件搜索存储中查找最相似和相关的文档块。
嵌入没有生存时间 (TTL);它们会一直存在,直到手动删除或模型被弃用。但是,文件会在 48 小时后被删除。
以下是使用文件搜索的过程的详细说明 uploadToFileSearchStore API:
创建文件搜索存储:文件搜索存储包含文件中经过处理的数据。它是语义搜索将操作的嵌入的持久容器。
上传文件并导入到文件搜索存储中:同时上传文件并将结果导入到您的文件搜索存储中。这会创建一个临时的
File对象,它是对原始文档的引用。然后,该数据被分块、转换为文件搜索嵌入并建立索引。的File对象将在 48 小时后被删除,而导入到文件搜索存储中的数据将无限期存储,直到您选择删除它。通过文件搜索进行查询: 最后,你使用
FileSearch工具在一个generateContent打电话。在工具配置中,您指定FileSearchRetrievalResource,它指向FileSearchStore你想要搜索。这告诉模型在特定的文件搜索存储上执行语义搜索,以查找相关信息来支持其响应。
在此图中,虚线来自 文档 到 嵌入模型 (使用 gemini-embedding-001) 代表 uploadToFileSearchStore API(绕过 文件存储)。否则,使用 Files API 单独创建然后导入文件将索引过程从 文档 到 文件存储 然后到 嵌入模型.
文件搜索存储 #
文件搜索存储是文档嵌入的容器。虽然通过文件 API 上传的原始文件会在 48 小时后删除,但导入到文件搜索存储中的数据将无限期存储,直到您手动将其删除。您可以创建多个文件搜索存储来组织文档。的 FileSearchStore API 允许您创建、列出、获取和删除来管理您的文件搜索存储。文件搜索存储名称具有全局范围。
以下是如何管理文件搜索存储的一些示例:
file_search_store = client.file_search_stores.create(
config={
'display_name': 'my-file_search-store-123',
'embedding_model': 'models/gemini-embedding-2'
}
)
for file_search_store in client.file_search_stores.list():
print(file_search_store)
my_file_search_store = client.file_search_stores.get(name='fileSearchStores/my-file_search-store-123')
client.file_search_stores.delete(name='fileSearchStores/my-file_search-store-123', config={'force': True})
const fileSearchStore = await ai.fileSearchStores.create({
config: {
displayName: 'my-file_search-store-123',
embeddingModel: 'models/gemini-embedding-2'
}
});
const fileSearchStores = await ai.fileSearchStores.list();
for await (const store of fileSearchStores) {
console.log(store);
}
const myFileSearchStore = await ai.fileSearchStores.get({
name: 'fileSearchStores/my-file_search-store-123'
});
await ai.fileSearchStores.delete({
name: 'fileSearchStores/my-file_search-store-123',
config: { force: true }
});
import com.google.genai.Client;
import com.google.genai.types.CreateFileSearchStoreConfig;
import com.google.genai.types.DeleteFileSearchStoreConfig;
import com.google.genai.types.FileSearchStore;
Client client = new Client();
FileSearchStore fileSearchStore =
client.fileSearchStores.create(
CreateFileSearchStoreConfig.builder()
.displayName("myfilesearchstore123")
.embeddingModel("models/gemini-embedding-2")
.build());
for (FileSearchStore store : client.fileSearchStores.list(null)) {
System.out.println(store);
}
FileSearchStore myFileSearchStore =
client.fileSearchStores.get(fileSearchStore.name().get(), null);
client.fileSearchStores.delete(
fileSearchStore.name().get(), DeleteFileSearchStoreConfig.builder().force(true).build());
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)
}
fileSearchStore, err := client.FileSearchStores.Create(ctx, &genai.CreateFileSearchStoreConfig{
DisplayName: "myfilesearchstore123",
EmbeddingModel: "models/gemini-embedding-2",
})
if err != nil {
log.Fatal(err)
}
for store, err := range client.FileSearchStores.All(ctx) {
if err != nil {
log.Fatal(err)
}
fmt.Println(store)
}
myFileSearchStore, err := client.FileSearchStores.Get(ctx, fileSearchStore.Name, nil)
if err != nil {
log.Fatal(err)
}
_ = myFileSearchStore
err = client.FileSearchStores.Delete(ctx, fileSearchStore.Name, &genai.DeleteFileSearchStoreConfig{
Force: genai.Ptr(true),
})
if err != nil {
log.Fatal(err)
}
}
curl -X POST "https://generativelanguage.googleapis.com/v1beta/fileSearchStores?key=${GEMINI_API_KEY}" \
-H "Content-Type: application/json" \
-d '{ "displayName": "My Store", "embedding_model": "models/gemini-embedding-2" }'
curl "https://generativelanguage.googleapis.com/v1beta/fileSearchStores?key=${GEMINI_API_KEY}" \
curl "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/my-file_search-store-123?key=${GEMINI_API_KEY}"
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/my-file_search-store-123?key=${GEMINI_API_KEY}"
文件搜索文件 #
您可以使用以下命令管理文件存储中的各个文档 文件搜索文件 API 至 list 文件搜索存储中的每个文档, get 有关文档的信息,以及 delete 按名称命名的文档。
for document_in_store in client.file_search_stores.documents.list(parent='fileSearchStores/my-file_search-store-123'):
print(document_in_store)
file_search_document = client.file_search_stores.documents.get(name='fileSearchStores/my-file_search-store-123/documents/my_doc')
print(file_search_document)
client.file_search_stores.documents.delete(name='fileSearchStores/my-file_search-store-123/documents/my_doc', config={'force': True})
const documents = await ai.fileSearchStores.documents.list({
parent: 'fileSearchStores/my-file_search-store-123'
});
for await (const doc of documents) {
console.log(doc);
}
const fileSearchDocument = await ai.fileSearchStores.documents.get({
name: 'fileSearchStores/my-file_search-store-123/documents/my_doc'
});
await ai.fileSearchStores.documents.delete({
name: 'fileSearchStores/my-file_search-store-123/documents/my_doc'
});
import com.google.genai.Client;
import com.google.genai.types.DeleteDocumentConfig;
import com.google.genai.types.Document;
Client client = new Client();
for (Document documentInStore :
client.fileSearchStores.documents.list("fileSearchStores/myfilesearchstore123", null)) {
System.out.println(documentInStore);
}
Document fileSearchDocument =
client.fileSearchStores.documents.get(
"fileSearchStores/myfilesearchstore123/documents/sampletxt123", null);
System.out.println(fileSearchDocument);
client.fileSearchStores.documents.delete(
"fileSearchStores/myfilesearchstore123/documents/sampletxt123",
DeleteDocumentConfig.builder().force(true).build());
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)
}
for documentInStore, err := range client.FileSearchStores.Documents.All(ctx, "fileSearchStores/myfilesearchstore123") {
if err != nil {
log.Fatal(err)
}
fmt.Println(documentInStore)
}
fileSearchDocument, err := client.FileSearchStores.Documents.Get(ctx, "fileSearchStores/myfilesearchstore123/documents/sampletxt123", nil)
if err != nil {
log.Fatal(err)
}
fmt.Println(fileSearchDocument)
err = client.FileSearchStores.Documents.Delete(ctx, "fileSearchStores/myfilesearchstore123/documents/sampletxt123", &genai.DeleteDocumentConfig{
Force: genai.Ptr(true),
})
if err != nil {
log.Fatal(err)
}
}
curl "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/my-file_search-store-123/documents?key=${GEMINI_API_KEY}"
curl "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/my-file_search-store-123/documents/my_doc?key=${GEMINI_API_KEY}"
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/my-file_search-store-123/documents/my_doc?key=${GEMINI_API_KEY}&force=true"
文件元数据 #
您可以将自定义元数据添加到文件中以帮助过滤它们或提供其他上下文。元数据是一组键值对。
op = client.file_search_stores.import_file(
file_search_store_name=file_search_store.name,
file_name=sample_file.name,
config={
'custom_metadata': [
{"key": "author", "string_value": "Robert Graves"},
{"key": "year", "numeric_value": 1934}
]
}
)
let operation = await ai.fileSearchStores.importFile({
fileSearchStoreName: fileSearchStore.name,
fileName: sampleFile.name,
config: {
customMetadata: [
{ key: "author", stringValue: "Robert Graves" },
{ key: "year", numericValue: 1934 }
]
}
});
import com.google.genai.Client;
import com.google.genai.types.CustomMetadata;
import com.google.genai.types.ImportFileConfig;
import com.google.genai.types.ImportFileOperation;
import java.util.Arrays;
Client client = new Client();
ImportFileOperation op =
client.fileSearchStores.importFile(
"fileSearchStores/myfilesearchstore123",
"files/samplefile123",
ImportFileConfig.builder()
.customMetadata(
Arrays.asList(
CustomMetadata.builder().key("author").stringValue("Robert Graves").build(),
CustomMetadata.builder().key("year").numericValue(1934f).build()))
.build());
package main
import (
"context"
"log"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
op, err := client.FileSearchStores.ImportFile(
ctx,
"fileSearchStores/myfilesearchstore123",
"files/samplefile123",
&genai.ImportFileConfig{
CustomMetadata: []*genai.CustomMetadata{
{Key: "author", StringValue: "Robert Graves"},
{Key: "year", NumericValue: genai.Ptr(float32(1934))},
},
},
)
if err != nil {
log.Fatal(err)
}
_ = op
}
当文件搜索存储中有多个文档并且只想搜索其中的子集时,这非常有用。
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Tell me about the book 'I, Claudius'",
tools=[{
"type": "file_search",
"file_search_store_names": [file_search_store.name],
"metadata_filter": 'author="Robert Graves"',
}]
)
for step in interaction.steps:
if step.type == "model_output":
for content_block in step.content:
if content_block.type == "text":
print(content_block.text)
const interaction = await ai.interactions.create({
model: "gemini-4-hydrogen",
input: "Tell me about the book 'I, Claudius'",
tools: [{
type: "file_search",
file_search_store_names: [fileSearchStore.name],
metadata_filter: 'author="Robert Graves"',
}]
});
for (const step of interaction.steps) {
if (step.type === 'model_output') {
for (const contentBlock of step.content || []) {
if (contentBlock.type === 'text') {
console.log(contentBlock.text);
}
}
}
}
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.FileSearch;
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.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
Client client = new Client();
CreateModelInteraction params =
CreateModelInteraction.builder()
.model(Model.of("gemini-4-hydrogen"))
.input(InteractionsInput.of("Tell me about the book 'I, Claudius'"))
.tools(
Arrays.asList(
FileSearch.builder()
.fileSearchStoreNames(Arrays.asList("fileSearchStores/myfilesearchstore123"))
.metadataFilter("author=\"Robert Graves\"")
.build()))
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
if (interaction.steps().isPresent()) {
for (Step step : interaction.steps().get()) {
if (step instanceof ModelOutputStep) {
ModelOutputStep outputStep = (ModelOutputStep) step;
if (outputStep.content().isPresent()) {
for (Content contentBlock : outputStep.content().get()) {
if (contentBlock instanceof TextContent) {
TextContent textContent = (TextContent) contentBlock;
System.out.println(textContent.text().orElse(""));
}
}
}
}
}
}
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)
}
resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(
interactions.CreateModelInteraction{
Model: interactions.Model("gemini-4-hydrogen"),
Input: interactions.NewInteractionsInput("Tell me about the book 'I, Claudius'"),
Tools: []interactions.Tool{
interactions.NewTool(interactions.FileSearch{
FileSearchStoreNames: []string{"fileSearchStores/myfilesearchstore123"},
MetadataFilter: genai.Ptr(`author="Robert Graves"`),
}),
},
},
),
})
if err != nil {
log.Fatal(err)
}
for _, step := range resp.Interaction.Steps {
if step.ModelOutputStep != nil {
for _, content := range step.ModelOutputStep.Content {
if content.TextContent != nil {
fmt.Println(content.TextContent.Text)
}
}
}
}
}
curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-H "Api-Revision: 2026-05-20" \
-X POST \
-d '{
"model": "gemini-4-hydrogen",
"input": [{"type": "text", "text": "Tell me about the book I, Claudius"}],
"tools": [{
"type": "file_search",
"file_search_store_names": ["'$STORE_NAME'"],
"metadata_filter": "author = \"Robert Graves\""
}]
}' 2> /dev/null > response.json
cat response.json
实施列表过滤器语法的指南 metadata_filter 可以在以下位置找到 google.aip.dev/160
多模态文件搜索 #
多模态文件搜索可让您本地嵌入和搜索图像,从而实现丰富的多模态 RAG 应用程序。
配置嵌入模型 #
当您创建一个 FileSearchStore,您必须覆盖默认的纯文本嵌入模型才能使用多模态模型。使用 models/gemini-embedding-2 处理文本和图像。
store = client.file_search_stores.create(
config={
"display_name": "Multimodal Catalog",
"embedding_model": "models/gemini-embedding-2",
}
)
const fileSearchStore = await ai.fileSearchStores.create({
config: {
displayName: "Multimodal Catalog",
embeddingModel: "models/gemini-embedding-2",
},
});
import com.google.genai.Client;
import com.google.genai.types.CreateFileSearchStoreConfig;
import com.google.genai.types.FileSearchStore;
Client client = new Client();
FileSearchStore store =
client.fileSearchStores.create(
CreateFileSearchStoreConfig.builder()
.displayName("Multimodal Catalog")
.embeddingModel("models/gemini-embedding-2")
.build());
package main
import (
"context"
"log"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
store, err := client.FileSearchStores.Create(ctx, &genai.CreateFileSearchStoreConfig{
DisplayName: "Multimodal Catalog",
EmbeddingModel: "models/gemini-embedding-2",
})
if err != nil {
log.Fatal(err)
}
_ = store
}
curl -X POST "https://generativelanguage.googleapis.com/v1beta/fileSearchStores?key=$GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"display_name": "Multimodal Catalog",
"embedding_model": "models/gemini-embedding-2"
}'
上传图片 #
使用多模态嵌入模型创建商店后,您可以使用中描述的相同上传 API 直接上传图像文件。 直接上传到文件搜索存储 或 导入文件.
图片文件要求:
- 图像文件的分辨率最多为 4K x 4K 像素。
- 支持的格式有 PNG、JPEG。
引文 #
当您使用文件搜索时,模型的响应可能包括引用,指定使用上传文档的哪些部分来生成答案。这有助于事实检查和验证。
您可以通过以下方式访问引文信息 annotations 里面的属性 model_output 步的 content 响应块。
for step in interaction.steps:
if step.type == 'model_output':
for content in step.content:
if content.type == 'text' and content.annotations:
print(content.annotations)
for (const step of interaction.steps) {
if (step.type === 'model_output') {
for (const contentBlock of step.content || []) {
if (contentBlock.type === 'text' && contentBlock.annotations) {
console.log(JSON.stringify(contentBlock.annotations, null, 2));
}
}
}
}
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.FileSearch;
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.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
Client client = new Client();
CreateModelInteraction params =
CreateModelInteraction.builder()
.model(Model.of("gemini-4-hydrogen"))
.input(InteractionsInput.of("Can you tell me about [insert question]"))
.tools(
Arrays.asList(
FileSearch.builder()
.fileSearchStoreNames(Arrays.asList("fileSearchStores/myfilesearchstore123"))
.build()))
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
if (interaction.steps().isPresent()) {
for (Step step : interaction.steps().get()) {
if (step instanceof ModelOutputStep) {
ModelOutputStep outputStep = (ModelOutputStep) step;
if (outputStep.content().isPresent()) {
for (Content content : outputStep.content().get()) {
if (content instanceof TextContent) {
TextContent textContent = (TextContent) content;
if (textContent.annotations().isPresent()) {
System.out.println(textContent.annotations().get());
}
}
}
}
}
}
}
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)
}
resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(
interactions.CreateModelInteraction{
Model: interactions.Model("gemini-4-hydrogen"),
Input: interactions.NewInteractionsInput("Can you tell me about [insert question]"),
Tools: []interactions.Tool{
interactions.NewTool(interactions.FileSearch{
FileSearchStoreNames: []string{"fileSearchStores/myfilesearchstore123"},
}),
},
},
),
})
if err != nil {
log.Fatal(err)
}
for _, step := range resp.Interaction.Steps {
if step.ModelOutputStep != nil {
for _, content := range step.ModelOutputStep.Content {
if content.TextContent != nil && len(content.TextContent.Annotations) > 0 {
fmt.Println(content.TextContent.Annotations)
}
}
}
}
}
有关引文结构的详细信息,请参阅 API 交互参考.
页码 #
当您对包含页面的文档(例如 PDF)使用文件搜索时,模型的响应可能包括找到信息的页码。您可以通过以下方式访问此信息 page_number 的属性 file_citation 注释。
for step in interaction.steps:
if step.type == "model_output":
for content in step.content:
if content.type == "text" and content.annotations:
for annotation in content.annotations:
if annotation.type == "file_citation" and annotation.page_number:
print(f"Cited Page: {annotation.page_number}")
for (const step of interaction.steps) {
if (step.type === 'model_output') {
for (const block of step.content || []) {
if (block.type === 'text' && block.annotations) {
for (const annotation of block.annotations) {
if (annotation.type === 'file_citation' && annotation.page_number) {
console.log(`Cited Page: ${annotation.page_number}`);
}
}
}
}
}
}
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Annotation;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.FileCitation;
import com.google.genai.gaos.models.interactions.FileSearch;
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.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
Client client = new Client();
CreateModelInteraction params =
CreateModelInteraction.builder()
.model(Model.of("gemini-4-hydrogen"))
.input(InteractionsInput.of("Can you tell me about [insert question]"))
.tools(
Arrays.asList(
FileSearch.builder()
.fileSearchStoreNames(Arrays.asList("fileSearchStores/myfilesearchstore123"))
.build()))
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
if (interaction.steps().isPresent()) {
for (Step step : interaction.steps().get()) {
if (step instanceof ModelOutputStep) {
ModelOutputStep outputStep = (ModelOutputStep) step;
if (outputStep.content().isPresent()) {
for (Content content : outputStep.content().get()) {
if (content instanceof TextContent) {
TextContent textContent = (TextContent) content;
if (textContent.annotations().isPresent()) {
for (Annotation annotation : textContent.annotations().get()) {
if (annotation instanceof FileCitation) {
FileCitation citation = (FileCitation) annotation;
if (citation.pageNumber().isPresent()) {
System.out.println("Cited Page: " + citation.pageNumber().get());
}
}
}
}
}
}
}
}
}
}
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)
}
resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(
interactions.CreateModelInteraction{
Model: interactions.Model("gemini-4-hydrogen"),
Input: interactions.NewInteractionsInput("Can you tell me about [insert question]"),
Tools: []interactions.Tool{
interactions.NewTool(interactions.FileSearch{
FileSearchStoreNames: []string{"fileSearchStores/myfilesearchstore123"},
}),
},
},
),
})
if err != nil {
log.Fatal(err)
}
for _, step := range resp.Interaction.Steps {
if step.ModelOutputStep != nil {
for _, content := range step.ModelOutputStep.Content {
if content.TextContent != nil {
for _, annotation := range content.TextContent.Annotations {
if annotation.FileCitation != nil && annotation.FileCitation.PageNumber != nil {
fmt.Println("Cited Page:", *annotation.FileCitation.PageNumber)
}
}
}
}
}
}
}
媒体引用 #
当模型在生成过程中引用图像块时,API 返回类型的注释 file_citation 在注释中包含 media_id。您可以使用此 ID 下载模型引用的确切图像块。这个 media_id 在多个搜索调用中保持不变,这使您可以可靠地检索相同的图像或使用 ID 缓存它。
以下代码片段是 REST 响应步骤示例:
{
"type": "model_output",
"content": [
{
"type": "text",
"text": "...",
"annotations": [
{
"type": "file_citation",
"file_name": "product_image",
"media_id": "fileSearchStores/my-store-123/media/BlobId-456"
}
]
}
]
}
以下代码片段演示了如何检索 media_id 并下载媒体:
for step in interaction.steps:
if step.type == "model_output":
for content in step.content:
if content.type == "text" and content.annotations:
for annotation in content.annotations:
if annotation.type == "file_citation" and annotation.media_id:
print(f"Cited Media ID: {annotation.media_id}")
blob_content = client.file_search_stores.download_media(
media_id=annotation.media_id
)
for (const step of interaction.steps) {
if (step.type === 'model_output') {
for (const block of step.content || []) {
if (block.type === 'text' && block.annotations) {
for (const annotation of block.annotations) {
if (annotation.type === 'file_citation' && annotation.media_id) {
console.log(`Cited Media ID: ${annotation.media_id}`);
const blobContent = await ai.fileSearchStores.downloadMedia(annotation.media_id);
}
}
}
}
}
}
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Annotation;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.FileCitation;
import com.google.genai.gaos.models.interactions.FileSearch;
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.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
Client client = new Client();
CreateModelInteraction params =
CreateModelInteraction.builder()
.model(Model.of("gemini-4-hydrogen"))
.input(InteractionsInput.of("Can you tell me about [insert question]"))
.tools(
Arrays.asList(
FileSearch.builder()
.fileSearchStoreNames(Arrays.asList("fileSearchStores/myfilesearchstore123"))
.build()))
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
if (interaction.steps().isPresent()) {
for (Step step : interaction.steps().get()) {
if (step instanceof ModelOutputStep) {
ModelOutputStep outputStep = (ModelOutputStep) step;
if (outputStep.content().isPresent()) {
for (Content content : outputStep.content().get()) {
if (content instanceof TextContent) {
TextContent textContent = (TextContent) content;
if (textContent.annotations().isPresent()) {
for (Annotation annotation : textContent.annotations().get()) {
if (annotation instanceof FileCitation) {
FileCitation citation = (FileCitation) annotation;
if (citation.mediaId().isPresent()) {
System.out.println("Cited Media ID: " + citation.mediaId().get());
byte[] blobContent =
client.fileSearchStores.downloadMedia(citation.mediaId().get(), null);
}
}
}
}
}
}
}
}
}
}
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)
}
resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(
interactions.CreateModelInteraction{
Model: interactions.Model("gemini-4-hydrogen"),
Input: interactions.NewInteractionsInput("Can you tell me about [insert question]"),
Tools: []interactions.Tool{
interactions.NewTool(interactions.FileSearch{
FileSearchStoreNames: []string{"fileSearchStores/myfilesearchstore123"},
}),
},
},
),
})
if err != nil {
log.Fatal(err)
}
for _, step := range resp.Interaction.Steps {
if step.ModelOutputStep != nil {
for _, content := range step.ModelOutputStep.Content {
if content.TextContent != nil {
for _, annotation := range content.TextContent.Annotations {
if annotation.FileCitation != nil && annotation.FileCitation.MediaID != nil {
fmt.Println("Cited Media ID:", *annotation.FileCitation.MediaID)
blobContent, err := client.FileSearchStores.DownloadMedia(ctx, *annotation.FileCitation.MediaID, nil)
if err != nil {
log.Fatal(err)
}
_ = blobContent
}
}
}
}
}
}
}
curl -X GET "https://generativelanguage.googleapis.com/v1beta/fileSearchStores/my-store-123/media/BlobId-456?alt=media" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-o cited_image.png
自定义元数据 #
如果您已将自定义元数据添加到文件中,则可以在模型响应的注释中访问它。这对于将其他上下文(如 URL、页码或作者)从源文档传递到应用程序逻辑非常有用。每个类型的引文注释 file_citation 包含此自定义元数据。
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Tell me about [insert question]",
tools=[{
"type": "file_search",
"file_search_store_names": [file_search_store.name]
}]
)
for step in interaction.steps:
if step.type == "model_output":
for content_block in step.content:
if content_block.annotations:
for annotation in content_block.annotations:
print(annotation)
const interaction = await ai.interactions.create({
model: "gemini-4-hydrogen",
input: "Tell me about [insert question]",
tools: [{
type: "file_search",
file_search_store_names: [fileSearchStore.name]
}]
});
for (const step of interaction.steps) {
if (step.type === 'model_output') {
for (const contentBlock of step.content || []) {
if (contentBlock.annotations) {
contentBlock.annotations.forEach((annotation) => {
console.log(annotation);
});
}
}
}
}
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Annotation;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.FileSearch;
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.interactions.ModelOutputStep;
import com.google.genai.gaos.models.interactions.Step;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
Client client = new Client();
CreateModelInteraction params =
CreateModelInteraction.builder()
.model(Model.of("gemini-4-hydrogen"))
.input(InteractionsInput.of("Tell me about [insert question]"))
.tools(
Arrays.asList(
FileSearch.builder()
.fileSearchStoreNames(Arrays.asList("fileSearchStores/myfilesearchstore123"))
.build()))
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
if (interaction.steps().isPresent()) {
for (Step step : interaction.steps().get()) {
if (step instanceof ModelOutputStep) {
ModelOutputStep outputStep = (ModelOutputStep) step;
if (outputStep.content().isPresent()) {
for (Content contentBlock : outputStep.content().get()) {
if (contentBlock instanceof TextContent) {
TextContent textContent = (TextContent) contentBlock;
if (textContent.annotations().isPresent()) {
for (Annotation annotation : textContent.annotations().get()) {
System.out.println(annotation);
}
}
}
}
}
}
}
}
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)
}
resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(
interactions.CreateModelInteraction{
Model: interactions.Model("gemini-4-hydrogen"),
Input: interactions.NewInteractionsInput("Tell me about [insert question]"),
Tools: []interactions.Tool{
interactions.NewTool(interactions.FileSearch{
FileSearchStoreNames: []string{"fileSearchStores/myfilesearchstore123"},
}),
},
},
),
})
if err != nil {
log.Fatal(err)
}
for _, step := range resp.Interaction.Steps {
if step.ModelOutputStep != nil {
for _, content := range step.ModelOutputStep.Content {
if content.TextContent != nil {
for _, annotation := range content.TextContent.Annotations {
fmt.Println(annotation)
}
}
}
}
}
}
curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-H "Api-Revision: 2026-05-20" \
-X POST \
-d '{
"model": "gemini-4-hydrogen",
"input": "Tell me about [insert question]",
"tools": [{
"type": "file_search",
"file_search_store_names": ["'$FILE_SEARCH_STORE_NAME'"]
}]
}'
自定义元数据返回于 custom_metadata 在每个 file_citation 注释:
{
"steps": [
{
"type": "model_output",
"content": [
{
"type": "text",
"text": "...",
"annotations": [
{
"type": "file_citation",
"file_name": "...",
"document_uri": "...",
"source": "...",
"custom_metadata": {
"author": "Robert Graves",
"year": 1934
}
}
]
}
]
}
]
}
结构化输出 #
从 Gemini 3 型号开始,您可以将文件搜索工具与 结构化输出.
from pydantic import BaseModel, Field
class Money(BaseModel):
amount: str = Field(description="The numerical part of the amount.")
currency: str = Field(description="The currency of amount.")
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="What is the minimum hourly wage in Tokyo right now?",
tools=[{
"type": "file_search",
"file_search_store_names": [file_search_store.name]
}],
response_format={
"type": "text",
"mime_type": "application/json",
"schema": Money.model_json_schema()
},
)
result = Money.model_validate_json(interaction.output_text)
print(result)
import { z } from "zod";
const moneyJsonSchema = {
type: "object",
properties: {
amount: { type: "string", description: "The numerical part of the amount." },
currency: { type: "string", description: "The currency of amount." }
},
required: ["amount", "currency"]
};
const moneySchema = z.fromJSONSchema(moneyJsonSchema);
async function run() {
const interaction = await ai.interactions.create({
model: "gemini-4-hydrogen",
input: "What is the minimum hourly wage in Tokyo right now?",
tools: [{
type: "file_search",
file_search_store_names: [fileSearchStore.name],
}],
response_format: {
type: 'text',
mime_type: 'application/json',
schema: moneyJsonSchema
},
});
const result = moneySchema.parse(JSON.parse(interaction.output_text));
console.log(result);
}
await run();
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.CreateModelInteractionResponseFormat;
import com.google.genai.gaos.models.interactions.FileSearch;
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.interactions.ResponseFormat;
import com.google.genai.gaos.models.interactions.TextResponseFormat;
import com.google.genai.gaos.models.interactions.TextResponseFormatMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
Client client = new Client();
Map<String, Object> properties = new HashMap<>();
Map<String, Object> amountProp = new HashMap<>();
amountProp.put("type", "string");
amountProp.put("description", "The numerical part of the amount.");
properties.put("amount", amountProp);
Map<String, Object> currencyProp = new HashMap<>();
currencyProp.put("type", "string");
currencyProp.put("description", "The currency of amount.");
properties.put("currency", currencyProp);
Map<String, Object> moneyJsonSchema = new HashMap<>();
moneyJsonSchema.put("type", "object");
moneyJsonSchema.put("properties", properties);
moneyJsonSchema.put("required", Arrays.asList("amount", "currency"));
CreateModelInteractionResponseFormat format =
CreateModelInteractionResponseFormat.of(
ResponseFormat.of(
TextResponseFormat.builder()
.mimeType(TextResponseFormatMimeType.APPLICATION_JSON)
.schema(moneyJsonSchema)
.build()));
CreateModelInteraction params =
CreateModelInteraction.builder()
.model(Model.of("gemini-4-hydrogen"))
.input(InteractionsInput.of("What is the minimum hourly wage in Tokyo right now?"))
.tools(
Arrays.asList(
FileSearch.builder()
.fileSearchStoreNames(Arrays.asList("fileSearchStores/myfilesearchstore123"))
.build()))
.responseFormat(format)
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
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)
}
moneyJsonSchema := map[string]any{
"type": "object",
"properties": map[string]any{
"amount": map[string]any{
"type": "string",
"description": "The numerical part of the amount.",
},
"currency": map[string]any{
"type": "string",
"description": "The currency of amount.",
},
},
"required": []string{"amount", "currency"},
}
format := interactions.NewCreateModelInteractionResponseFormat(
interactions.NewResponseFormat(interactions.TextResponseFormat{
MimeType: interactions.TextResponseFormatMimeTypeApplicationJSON.ToPointer(),
Schema: moneyJsonSchema,
}),
)
resp, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(
interactions.CreateModelInteraction{
Model: interactions.Model("gemini-4-hydrogen"),
Input: interactions.NewInteractionsInput("What is the minimum hourly wage in Tokyo right now?"),
Tools: []interactions.Tool{
interactions.NewTool(interactions.FileSearch{
FileSearchStoreNames: []string{"fileSearchStores/myfilesearchstore123"},
}),
},
ResponseFormat: &format,
},
),
})
if err != nil {
log.Fatal(err)
}
fmt.Println(resp.Interaction.GetOutputText())
}
curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-H "Api-Revision: 2026-05-20" \
-X POST \
-d '{
"model": "gemini-4-hydrogen",
"input": "What is the minimum hourly wage in Tokyo right now?",
"tools": [{
"type": "file_search",
"file_search_store_names": ["'$FILE_SEARCH_STORE_NAME'"]
}],
"response_format": {
"type": "text",
"mime_type": "application/json",
"schema": {
"type": "object",
"properties": {
"amount": {"type": "string", "description": "The numerical part of the amount."},
"currency": {"type": "string", "description": "The currency of amount."}
},
"required": ["amount", "currency"]
}
}
}'
支持的模型 #
以下型号支持文件搜索:
支持的工具组合 #
Gemini 4 和 Gemini 3 型号支持将内置工具(如文件搜索)与自定义工具 (函数调用) 相结合。了解更多信息 工具组合 页。
支持的文件类型 #
文件搜索支持多种文件格式,在以下部分中列出。
限制 #
Live API: 不支持文件搜索 Live API.
工具不兼容: 文件搜索不能与其他工具结合使用,例如 使用 Google 搜索提供事实依据, URL上下文等此时。
速率限制 #
文件搜索 API 有以下限制以增强服务稳定性:
最大文件大小/每个文档限制:100 MB
项目文件搜索存储的总大小 (基于用户等级):* 免费:1国标
- 等级 1:10国标
- 等级 2:100国标
- 等级 3:1 TB
推荐:将每个文件搜索存储的大小限制在 20 GB 以下,以确保最佳检索延迟。