google-gemini-file-search

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Gemini File Search

Status: Production Ready | Last Verified: 2025-11-18

状态: 已就绪可用于生产环境 | 最后验证日期: 2025-11-18

What Is File Search?

什么是File Search？

Google Gemini File Search is fully managed RAG (Retrieval-Augmented Generation):

Upload documents → Automatic chunking + embeddings + vector search + citations
No vector database setup required
100+ file formats supported (PDF, Word, Excel, code, Markdown, JSON, etc.)
Built-in grounding with citation metadata
Cost-effective: $0.15/1M tokens (one-time indexing), free storage + queries

Key difference from other RAG:

Cloudflare Vectorize: You manage chunking/embeddings
OpenAI Files API: Tied to Assistants API threads
File Search: Fully managed, standalone RAG

Google Gemini File Search是全托管式RAG（检索增强生成）：

上传文档 → 自动分块 + 嵌入向量 + 向量搜索 + 引用标注
无需搭建向量数据库
支持100多种文件格式（PDF、Word、Excel、代码、Markdown、JSON等）
内置带引用元数据的** grounding（事实锚定）**功能
高性价比：索引费用为$0.15/百万token（一次性收费），存储和查询免费

与其他RAG方案的核心区别:

Cloudflare Vectorize：需自行管理分块/嵌入向量
OpenAI Files API：与Assistants API线程绑定
File Search：全托管、独立式RAG服务

Quick Start (5 Minutes)

快速入门（5分钟）

1. Get API Key & Install

1. 获取API密钥并安装依赖

Get API key: https://aistudio.google.com/apikey (Free tier: 1 GB storage, 1,500 requests/day)

bash

bun add @google/genai

Version: 0.21.0+ | Node.js: 18+

获取API密钥：https://aistudio.google.com/apikey（免费额度：1GB存储，每日1500次请求）

bash

bun add @google/genai

版本要求: 0.21.0+ | Node.js版本: 18+

2. Basic Example

2. 基础示例

typescript

import { GoogleGenerativeAI } from '@google/genai';
import fs from 'fs';

const ai = new GoogleGenerativeAI(process.env.GOOGLE_AI_API_KEY);

// Create store
const fileStore = await ai.fileSearchStores.create({
  config: { displayName: 'my-knowledge-base' }
});

// Upload document
const operation = await ai.fileSearchStores.uploadToFileSearchStore({
  name: fileStore.name,
  file: fs.createReadStream('./manual.pdf'),
  config: {
    displayName: 'Installation Manual',
    chunkingConfig: {
      whiteSpaceConfig: {
        maxTokensPerChunk: 500,
        maxOverlapTokens: 50
      }
    }
  }
});

// Poll until done
while (!operation.done) {
  await new Promise(resolve => setTimeout(resolve, 1000));
  operation = await ai.operations.get({ name: operation.name });
}

// Query documents
const model = ai.getGenerativeModel({
  model: 'gemini-2.5-pro',  // Only 2.5 Pro/Flash supported
  tools: [{
    fileSearchTool: {
      fileSearchStores: [fileStore.name]
    }
  }]
});

const result = await model.generateContent('How do I install the product?');
console.log(result.response.text());

// Get citations
const grounding = result.response.candidates[0].groundingMetadata;
if (grounding) {
  console.log('Sources:', grounding.groundingChunks);
}

Load
references/setup-guide.md
for complete walkthrough with batch uploads, error handling, and production checklist.

typescript

import { GoogleGenerativeAI } from '@google/genai';
import fs from 'fs';

const ai = new GoogleGenerativeAI(process.env.GOOGLE_AI_API_KEY);

// 创建存储库
const fileStore = await ai.fileSearchStores.create({
  config: { displayName: 'my-knowledge-base' }
});

// 上传文档
const operation = await ai.fileSearchStores.uploadToFileSearchStore({
  name: fileStore.name,
  file: fs.createReadStream('./manual.pdf'),
  config: {
    displayName: 'Installation Manual',
    chunkingConfig: {
      whiteSpaceConfig: {
        maxTokensPerChunk: 500,
        maxOverlapTokens: 50
      }
    }
  }
});

// 轮询直到处理完成
while (!operation.done) {
  await new Promise(resolve => setTimeout(resolve, 1000));
  operation = await ai.operations.get({ name: operation.name });
}

// 查询文档
const model = ai.getGenerativeModel({
  model: 'gemini-2.5-pro',  // 仅支持2.5 Pro/Flash
  tools: [{
    fileSearchTool: {
      fileSearchStores: [fileStore.name]
    }
  }]
});

const result = await model.generateContent('How do I install the product?');
console.log(result.response.text());

// 获取引用来源
const grounding = result.response.candidates[0].groundingMetadata;
if (grounding) {
  console.log('Sources:', grounding.groundingChunks);
}

如需完整指南（包括批量上传、错误处理、生产环境检查清单），请查看
references/setup-guide.md

Critical Rules

核心规则

Always Do

务必遵循

Use delete + re-upload for updates (documents are immutable)
Calculate 3x storage (embeddings + metadata = ~3x file size)
Configure chunking (500 tokens for technical docs, 800 for prose)
Poll operations until
```
done: true
```
(with timeout)
Use force: true when deleting stores with documents
Use Gemini 2.5 models only (2.5-pro or 2.5-flash)
Keep metadata under 20 fields per document
Estimate indexing costs ($0.15/1M tokens one-time)

更新文档请使用「删除+重新上传」模式（文档为不可变状态）
按3倍文件大小估算存储需求（嵌入向量+元数据约为文件大小的3倍）
配置分块参数（技术文档建议500token/块，散文建议800token/块）
轮询操作直到
done: true
（需设置超时时间）
删除包含文档的存储库时请添加
force: true
参数
仅使用Gemini 2.5系列模型（2.5-pro或2.5-flash）
单文档元数据字段不超过20个
提前估算索引成本（一次性收费$0.15/百万token）

Never Do

切勿操作

Never try to update documents (no PATCH API exists)
Never assume storage = file size (it's 3x)
Never skip chunking config (defaults may not be optimal)
Never upload without polling (operation may still be processing)
Never delete without force if store has documents
Never use Gemini 1.5 models (File Search requires 2.5)
Never exceed 20 metadata fields (hard limit)
Never upload large files without cost estimate

切勿尝试直接更新现有文档（无PATCH API）
切勿认为存储需求等于文件大小（实际为3倍）
切勿跳过分块配置（默认参数可能非最优）
切勿上传后不轮询状态（操作可能仍在处理中）
删除包含文档的存储库时切勿省略
force: true
切勿使用Gemini 1.5系列模型（File Search仅支持2.5版本）
切勿超过20个元数据字段限制（硬性限制）
切勿未经成本估算就上传大文件

Top 3 Errors Prevented

三大常见问题及解决方案

Error 1: Document Immutability

问题1：文档不可变

Problem: Trying to update existing document

Solution: Delete + re-upload pattern

typescript

// Find and delete old version
const docs = await ai.fileSearchStores.documents.list({
  parent: fileStore.name
});
const oldDoc = docs.documents.find(d => d.displayName === 'manual.pdf');
if (oldDoc) {
  await ai.fileSearchStores.documents.delete({
    name: oldDoc.name,
    force: true
  });
}

// Upload new version
await ai.fileSearchStores.uploadToFileSearchStore({
  name: fileStore.name,
  file: fs.createReadStream('manual-v2.pdf'),
  config: { displayName: 'manual.pdf' }
});

问题描述: 尝试更新已存在的文档

解决方案: 使用删除+重新上传模式

typescript

// 查找并删除旧版本
const docs = await ai.fileSearchStores.documents.list({
  parent: fileStore.name
});
const oldDoc = docs.documents.find(d => d.displayName === 'manual.pdf');
if (oldDoc) {
  await ai.fileSearchStores.documents.delete({
    name: oldDoc.name,
    force: true
  });
}

// 上传新版本
await ai.fileSearchStores.uploadToFileSearchStore({
  name: fileStore.name,
  file: fs.createReadStream('manual-v2.pdf'),
  config: { displayName: 'manual.pdf' }
});

Error 2: Storage Quota Exceeded

问题2：存储配额超限

Problem: Storage calculation wrong (3x multiplier)

Solution: Estimate before upload

typescript

const fileSize = fs.statSync('data.pdf').size;
const estimatedStorage = fileSize * 3;  // Embeddings + metadata

if (estimatedStorage > 1e9) {
  console.warn('⚠️ May exceed free tier 1 GB limit');
}

问题描述: 存储需求计算错误（未考虑3倍系数）

解决方案: 上传前提前估算

typescript

const fileSize = fs.statSync('data.pdf').size;
const estimatedStorage = fileSize * 3;  // 嵌入向量+元数据

if (estimatedStorage > 1e9) {
  console.warn('⚠️ 可能超出免费额度1GB限制');
}

Error 3: Model Compatibility

问题3：模型兼容性

Problem: Using wrong model version

Solution: Use Gemini 2.5 only

typescript

// ✅ CORRECT
const model = ai.getGenerativeModel({
  model: 'gemini-2.5-pro',  // or gemini-2.5-flash
  tools: [{ fileSearchTool: { fileSearchStores: [storeName] } }]
});

// ❌ WRONG
const model = ai.getGenerativeModel({
  model: 'gemini-1.5-pro',  // Not supported!
  tools: [{ fileSearchTool: { fileSearchStores: [storeName] } }]
});

Load
references/error-catalog.md
for all 8 errors with detailed solutions including chunking, operation polling, metadata limits, and force delete requirements.

问题描述: 使用了不兼容的模型版本

解决方案: 仅使用Gemini 2.5系列模型

typescript

// ✅ 正确用法
const model = ai.getGenerativeModel({
  model: 'gemini-2.5-pro',  // 或gemini-2.5-flash
  tools: [{ fileSearchTool: { fileSearchStores: [storeName] } }]
});

// ❌ 错误用法
const model = ai.getGenerativeModel({
  model: 'gemini-1.5-pro',  // 不支持!
  tools: [{ fileSearchTool: { fileSearchStores: [storeName] } }]
});

如需查看全部8种常见问题及详细解决方案（包括分块、轮询、元数据限制、强制删除等），请查看
references/error-catalog.md

When to Use File Search

适用场景

Use File Search When:

适合使用File Search的场景:

Want fully managed RAG (no vector DB)
Cost predictability matters (one-time indexing)
Need 100+ file format support
Citations are important (built-in grounding)
Simple deployment is priority
Documents are relatively static

想要全托管式RAG（无需维护向量数据库）
重视成本可预测性（一次性索引收费）
需要支持100多种文件格式
需内置引用标注功能
优先考虑部署简洁性
文档相对静态

Use Alternatives When:

适合使用其他方案的场景:

Cloudflare Vectorize - Global edge performance, custom embeddings, real-time R2 updates OpenAI Files API - Assistants API, conversational threads, very large collections (10,000+)

Cloudflare Vectorize - 全球边缘性能、自定义嵌入向量、实时R2更新 OpenAI Files API - 与Assistants API集成、对话线程、超大规模文档集（10000+）

Common Patterns

常见实现模式

Pattern 1: Customer Support Knowledge Base

模式1：客户支持知识库

typescript

// Upload support docs with metadata
await ai.fileSearchStores.uploadToFileSearchStore({
  name: fileStore.name,
  file: fs.createReadStream('troubleshooting.pdf'),
  config: {
    displayName: 'Troubleshooting Guide',
    customMetadata: {
      doc_type: 'support',
      category: 'troubleshooting',
      language: 'en'
    }
  }
});

typescript

// 上传带元数据的支持文档
await ai.fileSearchStores.uploadToFileSearchStore({
  name: fileStore.name,
  file: fs.createReadStream('troubleshooting.pdf'),
  config: {
    displayName: 'Troubleshooting Guide',
    customMetadata: {
      doc_type: 'support',
      category: 'troubleshooting',
      language: 'en'
    }
  }
});

Pattern 2: Batch Document Upload

模式2：批量文档上传

typescript

const files = ['doc1.pdf', 'doc2.md', 'doc3.docx'];
const uploadPromises = files.map(file =>
  ai.fileSearchStores.uploadToFileSearchStore({
    name: fileStore.name,
    file: fs.createReadStream(file),
    config: { displayName: file }
  })
);
const operations = await Promise.all(uploadPromises);

// Poll all operations
for (const op of operations) {
  let operation = op;
  while (!operation.done) {
    await new Promise(resolve => setTimeout(resolve, 1000));
    operation = await ai.operations.get({ name: operation.name });
  }
  console.log('✅', operation.response.displayName);
}

typescript

const files = ['doc1.pdf', 'doc2.md', 'doc3.docx'];
const uploadPromises = files.map(file =>
  ai.fileSearchStores.uploadToFileSearchStore({
    name: fileStore.name,
    file: fs.createReadStream(file),
    config: { displayName: file }
  })
);
const operations = await Promise.all(uploadPromises);

// 轮询所有操作
for (const op of operations) {
  let operation = op;
  while (!operation.done) {
    await new Promise(resolve => setTimeout(resolve, 1000));
    operation = await ai.operations.get({ name: operation.name });
  }
  console.log('✅', operation.response.displayName);
}

Pattern 3: Document Update Flow

模式3：文档更新流程

typescript

// 1. List existing documents
const docs = await ai.fileSearchStores.documents.list({
  parent: fileStore.name
});

// 2. Delete old version
const oldDoc = docs.documents.find(d => d.displayName === 'manual.pdf');
if (oldDoc) {
  await ai.fileSearchStores.documents.delete({
    name: oldDoc.name,
    force: true
  });
}

// 3. Upload new version
const operation = await ai.fileSearchStores.uploadToFileSearchStore({
  name: fileStore.name,
  file: fs.createReadStream('manual-v2.pdf'),
  config: {
    displayName: 'manual.pdf',
    customMetadata: {
      version: '2.0',
      updated_at: new Date().toISOString()
    }
  }
});

// 4. Poll until done
while (!operation.done) {
  await new Promise(resolve => setTimeout(resolve, 1000));
  operation = await ai.operations.get({ name: operation.name });
}

Load
references/setup-guide.md
for additional patterns including code documentation search and internal knowledge bases.

typescript

// 1. 列出现有文档
const docs = await ai.fileSearchStores.documents.list({
  parent: fileStore.name
});

// 2. 删除旧版本
const oldDoc = docs.documents.find(d => d.displayName === 'manual.pdf');
if (oldDoc) {
  await ai.fileSearchStores.documents.delete({
    name: oldDoc.name,
    force: true
  });
}

// 3. 上传新版本
const operation = await ai.fileSearchStores.uploadToFileSearchStore({
  name: fileStore.name,
  file: fs.createReadStream('manual-v2.pdf'),
  config: {
    displayName: 'manual.pdf',
    customMetadata: {
      version: '2.0',
      updated_at: new Date().toISOString()
    }
  }
});

// 4. 轮询直到处理完成
while (!operation.done) {
  await new Promise(resolve => setTimeout(resolve, 1000));
  operation = await ai.operations.get({ name: operation.name });
}

如需查看更多模式（包括代码文档搜索、内部知识库），请查看
references/setup-guide.md

When to Load References

何时查看参考文档

Load

references/setup-guide.md

when:

当以下情况时查看

references/setup-guide.md

First-time File Search setup
Need step-by-step walkthrough with all configuration options
Configuring batch upload strategies
Production deployment checklist
Complete API initialization patterns

首次设置File Search
需要包含所有配置选项的分步指南
配置批量上传策略
查看生产环境部署检查清单
完整的API初始化模式

Load

references/error-catalog.md

when:

当以下情况时查看

references/error-catalog.md

Encountering any of 8 common errors
Need detailed error solutions with code examples
Prevention checklist required
Troubleshooting upload/query issues
Understanding chunking, metadata, or cost calculation problems

遇到8种常见错误之一
需要带代码示例的详细错误解决方案
需要预防问题的检查清单
排查上传/查询问题
理解分块、元数据或成本计算问题

Supported File Formats

支持的文件格式

100+ formats including:

Documents: PDF, Word (.docx), Excel (.xlsx), PowerPoint (.pptx)
Text: Markdown (.md), Plain text (.txt), JSON, CSV
Code: Python, JavaScript, TypeScript, Java, C++, Go, Rust, etc.

Not supported: Images in PDFs (text extraction only), Audio files, Video files

支持100多种格式，包括:

文档类: PDF、Word (.docx)、Excel (.xlsx)、PowerPoint (.pptx)
文本类: Markdown (.md)、纯文本 (.txt)、JSON、CSV
代码类: Python、JavaScript、TypeScript、Java、C++、Go、Rust等

不支持: PDF中的图片（仅提取文本）、音频文件、视频文件

Pricing

定价

Indexing (one-time): $0.15 per 1M tokens Storage: Free (10 GB - 1 TB depending on tier) Query embeddings: Free (retrieved context counts as input tokens)

Example: 1,000-page document ≈ 500k tokens → Indexing cost: $0.075 → Storage: ~1.5 GB (3x multiplier)

索引（一次性）: 每百万token $0.15 存储: 免费（根据套餐不同为10GB-1TB） 查询嵌入向量: 免费（检索到的上下文计入输入token）

示例: 1000页文档 ≈ 50万token → 索引费用: $0.075 → 存储需求: ~1.5GB（3倍系数）

Chunking Guidelines

分块指南

Technical docs: 500 tokens/chunk, 50 overlap Prose: 800 tokens/chunk, 80 overlap Legal: 300 tokens/chunk, 30 overlap

typescript

chunkingConfig: {
  whiteSpaceConfig: {
    maxTokensPerChunk: 500,  // Smaller = more precise
    maxOverlapTokens: 50     // 10% overlap recommended
  }
}

技术文档: 500token/块，重叠50token 散文: 800token/块，重叠80token 法律文档: 300token/块，重叠30token

typescript

chunkingConfig: {
  whiteSpaceConfig: {
    maxTokensPerChunk: 500,  // 块越小，精度越高
    maxOverlapTokens: 50     // 推荐10%重叠率
  }
}

Resources

资源

References (

references/

```
setup-guide.md
```
- Complete setup walkthrough (authentication, store creation, file upload, batch patterns, production checklist)
```
error-catalog.md
```
- All 8 documented errors with solutions (immutability, storage, chunking, metadata, costs, polling, force delete, model compatibility)

Official Documentation:

File Search Overview: https://ai.google.dev/api/file-search
API Reference: https://ai.google.dev/api/file-search/documents
Blog Post: https://blog.google/technology/developers/file-search-gemini-api/

Questions? Issues?

Check
```
references/setup-guide.md
```
for complete setup
Review
```
references/error-catalog.md
```
for all 8 errors
Verify model version (must be Gemini 2.5)
Check storage calculation (3x file size)

参考文档 (

references/

```
setup-guide.md
```
- 完整设置指南（认证、存储库创建、文件上传、批量模式、生产环境检查清单）
```
error-catalog.md
```
- 全部8种已记录错误及解决方案（不可变性、存储、分块、元数据、成本、轮询、强制删除、模型兼容性）

官方文档:

File Search概述: https://ai.google.dev/api/file-search
API参考: https://ai.google.dev/api/file-search/documents
博客文章: https://blog.google/technology/developers/file-search-gemini-api/

有疑问？遇到问题？

查看
```
references/setup-guide.md
```
获取完整设置说明
查看
```
references/error-catalog.md
```
获取全部8种错误的解决方案
验证模型版本（必须为Gemini 2.5）
检查存储计算（3倍文件大小）

google-gemini-file-search

Original

Translation

Google Gemini File Search

Google Gemini File Search

What Is File Search?

什么是File Search？

Quick Start (5 Minutes)

快速入门（5分钟）

1. Get API Key & Install

1. 获取API密钥并安装依赖

2. Basic Example

2. 基础示例

Critical Rules

核心规则

Always Do

务必遵循

Never Do

切勿操作

Top 3 Errors Prevented

三大常见问题及解决方案

Error 1: Document Immutability

问题1：文档不可变

Error 2: Storage Quota Exceeded

问题2：存储配额超限

Error 3: Model Compatibility

问题3：模型兼容性

When to Use File Search

适用场景

Use File Search When:

适合使用File Search的场景:

Use Alternatives When:

适合使用其他方案的场景:

Common Patterns

常见实现模式

Pattern 1: Customer Support Knowledge Base

模式1：客户支持知识库

Pattern 2: Batch Document Upload

模式2：批量文档上传

Pattern 3: Document Update Flow

模式3：文档更新流程

When to Load References

何时查看参考文档

Load references/setup-guide.md when:

当以下情况时查看references/setup-guide.md:

Load references/error-catalog.md when:

当以下情况时查看references/error-catalog.md:

Supported File Formats

支持的文件格式

Pricing

定价

Chunking Guidelines

分块指南

Resources

资源

Load
`references/setup-guide.md`
when:

当以下情况时查看
`references/setup-guide.md`
:

Load
`references/error-catalog.md`
when:

当以下情况时查看
`references/error-catalog.md`
: