name: google-gemini-file-search description: Google Gemini 文件搜索用于托管式检索增强生成，支持100多种文件格式。适用于文档问答、知识库构建，或遇到不可变性错误、配额问题、轮询失败等情况。支持Gemini 3 Pro/Flash（Gemini 2.5 旧版）。 license: MIT metadata: version: “2.0.0” last_verified: “2025-11-18” production_tested: true token_savings: “~65%” errors_prevented: 8 templates_included: 0 references_included: 2

Google Gemini 文件搜索

状态：生产就绪 | 最后验证：2025-11-18

什么是文件搜索？

Google Gemini 文件搜索是完全托管的检索增强生成：

上传文档 → 自动分块 + 嵌入向量 + 向量搜索 + 引用
无需向量数据库设置
支持100多种文件格式（PDF、Word、Excel、代码、Markdown、JSON等）
内置基础，带引用元数据
成本效益高：每100万令牌0.15美元（一次性索引），免费存储 + 查询

与其他RAG的关键区别：

Cloudflare Vectorize：您管理分块/嵌入向量
OpenAI Files API：绑定到助手API线程
文件搜索：完全托管、独立的RAG

快速入门（5分钟）

1. 获取API密钥并安装

获取API密钥：https://aistudio.google.com/apikey（免费层：1 GB存储，每天1,500次请求）

bun add @google/genai

版本：0.21.0+ | Node.js：18+

2. 基本示例

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: '我的知识库' }
});

// 上传文档
const operation = await ai.fileSearchStores.uploadToFileSearchStore({
  name: fileStore.name,
  file: fs.createReadStream('./manual.pdf'),
  config: {
    displayName: '安装手册',
    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('如何安装产品？');
console.log(result.response.text());

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

加载 references/setup-guide.md 获取完整教程，包括批量上传、错误处理和产品清单。

关键规则

必须做

使用删除 + 重新上传 进行更新（文档不可变）
计算3倍存储（嵌入向量 + 元数据 ≈ 3倍文件大小）
配置分块（技术文档500令牌，散文800令牌）
轮询操作 直到 done: true（带超时）
使用 force: true 当删除含有文档的存储时
使用Gemini 2.5模型 仅（2.5-pro 或 2.5-flash）
保持元数据少于20个字段 每文档
估算索引成本（每100万令牌0.15美元一次性）

绝不做

绝不要尝试更新 文档（无PATCH API）
绝不要假设存储 = 文件大小（是3倍）
绝不要跳过分块配置（默认可能不优化）
绝不要无轮询上传（操作可能仍在处理）
绝不要无force删除 如果存储有文档
绝不要使用Gemini 1.5模型（文件搜索需要2.5）
绝不要超过20个元数字段（硬限制）
绝不要无成本估算上传大文件

前三错误预防

错误1：文档不可变性

问题：尝试更新现有文档

解决方案：删除 + 重新上传模式

// 查找并删除旧版本
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' }
});

错误2：存储配额超出

问题：存储计算错误（3倍乘数）

解决方案：上传前估算

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

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

错误3：模型兼容性

问题：使用错误模型版本

解决方案：仅使用Gemini 2.5

// ✅ 正确
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] } }]
});

加载 references/error-catalog.md 获取所有8个错误的详细解决方案，包括分块、操作轮询、元数据限制和强制删除要求。

何时使用文件搜索

使用文件搜索当：

需要完全托管RAG（无向量数据库）
成本可预测性重要（一次性索引）
需要100多种文件格式支持
引用重要（内置基础）
简单部署是优先
文档相对静态

使用替代品当：

Cloudflare Vectorize - 全球边缘性能，自定义嵌入向量，实时R2更新 OpenAI Files API - 助手API，对话线程，极大集合（10,000+）

常见模式

模式1：客户支持知识库

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

模式2：批量文档上传

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);
}

模式3：文档更新流程

// 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 获取附加模式，包括代码文档搜索和内部知识库。

何时加载参考文献

加载 `references/setup-guide.md` 当：

首次文件搜索设置
需要分步教程带所有配置选项
配置批量上传策略
产品部署清单
完整API初始化模式

加载 `references/error-catalog.md` 当：

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

支持的文件格式

100多种格式包括：

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

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

定价

索引（一次性）：每100万令牌0.15美元存储：免费（10 GB - 1 TB取决于层级） 查询嵌入向量：免费（检索上下文计入输入令牌）

示例：1,000页文档 ≈ 50万令牌 → 索引成本：0.075美元 → 存储：~1.5 GB（3倍乘数）

分块指南

技术文档：500令牌/块，50重叠散文：800令牌/块，80重叠法律：300令牌/块，30重叠

chunkingConfig: {
  whiteSpaceConfig: {
    maxTokensPerChunk: 500,  // 较小 = 更精确
    maxOverlapTokens: 50     // 推荐10%重叠
  }
}

资源

参考文献 (references/)：

setup-guide.md - 完整设置教程（认证、存储创建、文件上传、批量模式、产品清单）
error-catalog.md - 所有8个记录错误带解决方案（不可变性、存储、分块、元数据、成本、轮询、强制删除、模型兼容性）

官方文档：

文件搜索概览：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倍文件大小）