Gemini · Files, embeddings, and RAG with Google
You can hand Gemini a 200-page employee handbook, ask "how many remote days do I get in my second year?" and get a grounded answer with the exact clause. This lesson shows you four ways to do that on Google AI, from "just upload the file" to "build real retrieval over a document set," and when to reachreachThe number of unique people exposed to your message in a given period. Unlike impressions, reach counts each person once, no matter how often they see it.View full definition → for each.
Retrieval strategies, ranked by effort
Before any code, get the decision right. People waste weeks building the wrong one.
- Long context (put the file in the prompt). Gemini's context windowcontext windowThe context window is the maximum amount of text (measured in tokens) a language model can process at once, including both the input prompt and the generated output.View full definition → can hold entire documents. For a single handbook, you may not need RAGRAGA method that lets an AI model answer using your own documents, retrieving relevant passages before generating a response instead of relying only on training data.View full definition → at all.
- The File API. For files too big to inline, or files you reuse across many requests, upload once and reference the handle. This is still long-context retrieval, just managed better.
- The File Search tool. This is managed RAG inside the Gemini APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition →. You upload documents to a store, and Gemini retrieves the relevant chunks for you, with citations.
- Your own embeddings + vector store. You need this when you want full control over chunking, ranking, or where vectors live.
The instinct from the foundations block is to jump to RAG. Resist it. If the whole corpus fits in context, long context beats RAG on accuracy and simplicity.
Strategy 1: Just upload the file
In Google AI Studio, drag your handbook PDF into a prompt and ask. Gemini reads the PDF directly, including tables and layout, with no OCR step.
For the API, you can send small files inline as bytes. Once a file is large, or you will ask many questions against it, use the File API instead.
Strategy 2: The File API for large, reusable files
The File API stores a file on Google's side and gives you a handle. You upload once, then reference it across many requests without re-sending bytes. Uploaded files are kept for a limited period (currently around 48 hours) and are free to store. That makes this a good fit for a "load the handbook, ask ten questions" session.
from google import genai
client = genai.Client() # reads GEMINI_API_KEY from env
handbook = client.files.upload(file="employee_handbook.pdf")
resp = client.models.generate_content(
model="gemini-2.5-flash",
contents=[
handbook,
"How many remote work days am I allowed in my second year? "
"Quote the exact policy clause and its section number.",
],
)
print(resp.text)That is the whole "answer from our handbook" flow for a single document. A Flash-tier model is the right choice here because it is fast, cheap, and can easily read one PDF. Save Pro for harder reasoning over messy, multi-document inputs. Model IDs change as new generations ship (the Gemini 3 family is now available). Check the models page and swap in the current Flash ID.
Upload limits and supported types are listed in the Files guide. Check it rather than guessing at size caps, which change.
Long context and the File API in Gemini
When long context stops being enough
Long context works well until it doesn't. Three signals tell you to move to real RAG:
- The corpus exceeds the window: fifty handbooks, a wiki export, years of policy memos.
- Cost per query matters. You pay for input tokenstokensA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition →, so sending the whole handbook on each of 10,000 daily questions is wasteful when each answer needs two paragraphs.
- You need precise, citable provenance across many sources, not "somewhere in this big blob."
Strategy 3: the file search tool (managed RAG in the Gemini API)
Since late 2025, the Gemini API has a built-in File Search tool. You create a store and upload documents to it. Google chunks, embeds, and indexes them. At query time, you pass the store as a tool, and Gemini retrieves the relevant passages and returns citations in the response's grounding metadata. You do not have to run a vector databasevector databaseA vector database stores data as high-dimensional numeric vectors (embeddings) and retrieves items by similarity rather than exact matches, powering semantic search and AI applications.View full definition →.
import time
from google import genai
from google.genai import types
client = genai.Client()
store = client.file_search_stores.create(config={"display_name": "hr-policies"})
op = client.file_search_stores.upload_to_file_search_store(
file="employee_handbook.pdf",
file_search_store_name=store.name,
)
while not op.done:
time.sleep(5)
op = client.operations.get(op)
resp = client.models.generate_content(
model="gemini-2.5-flash",
contents="How many remote days do I get in my second year?",
config=types.GenerateContentConfig(
tools=[types.Tool(file_search=types.FileSearch(
file_search_store_names=[store.name]
))]
),
)
print(resp.text)
print(resp.candidates[0].grounding_metadata) # which chunks were usedUnlike the File API's 48-hour files, documents in a store persist until you delete them. At launch, Google charged for embeddingembeddingAn embedding is a numerical vector that represents data (text, images, or items) in a way that captures meaning, so similar items sit close together in space.View full definition → at indexing time (about $0.15 per million tokens), while storage and query-time embeddings were free. Confirm current pricing and limits in the File Search docs.
For most "make our 50 policy PDFs answerable" projects, this is now the default starting point.
Strategy 4: Your own embeddings and vector store
Build the pipelinepipelineAll active sales opportunities across the stages of the sales process, together with their combined potential value and probability of closing.View full definition → yourself when you want to control chunking, mix in keyword search, rerank results, or keep vectors in a database you already run.
An embedding is a vector (a list of numbers) that captures the meaning of a chunk of text, so similar chunks sit near each other. You embed the chunks once and store them. At query time, you embed the question and retrieve the nearest chunks.
Google's embedding model is gemini-embedding-001. It supports a task type parameter: use RETRIEVAL_DOCUMENT for stored chunks and RETRIEVAL_QUERY for the search question. Skipping this setting is the most common mistake, and it costs retrieval quality.
Step 1: Chunk and embed your documents
chunks = [
"Section 4.2 Remote Work: In their second year of employment, "
"staff are entitled to up to 80 remote working days per year...",
"Section 4.3 Equipment: The company provides a laptop and...",
]
doc_vectors = client.models.embed_content(
model="gemini-embedding-001",
contents=chunks,
config={"task_type": "RETRIEVAL_DOCUMENT"},
).embeddingsFor a small internal tool, an in-memory list with cosine similarity is fine.
Step 2: Embed the query and retrieve
import numpy as np
def cosine(a, b):
a, b = np.array(a), np.array(b)
return a @ b / (np.linalg.norm(a) * np.linalg.norm(b))
question = "How many remote days do I get in my second year?"
q_vec = client.models.embed_content(
model="gemini-embedding-001",
contents=[question],
config={"task_type": "RETRIEVAL_QUERY"},
).embeddings[0].values
scored = sorted(
zip(chunks, doc_vectors),
key=lambda c: cosine(q_vec, c[1].values),
reverse=True,
)
top_chunks = [c[0] for c in scored[:3]]Step 3: Generate a grounded answer
context = "\n\n".join(top_chunks)
resp = client.models.generate_content(
model="gemini-2.5-flash",
contents=(
f"Answer using ONLY the handbook excerpts below. "
f"Cite the section number. If the answer is not present, say so.\n\n"
f"{context}\n\nQuestion: {question}"
),
)
print(resp.text)The instruction to answer only from the excerpts, and to say so when the answer is absent, is your guardrail against hallucination. RAG alone does not stop a model from inventing answers. This applies to File Search too, so put the same instruction in your prompt there.
Knowledge check
1. According to the lesson, when should you prefer long context over building a true RAG pipeline?
2. What is the primary purpose of Google's File API compared to sending a file inline?
3. Why does the lesson say native multimodality removes the need for an OCR step when uploading a PDF?
4. Select ALL scenarios where true RAG (embeddings + a vector store) is the appropriate choice.
Select all the correct answers.
5. Select ALL statements that correctly describe the File API as presented in the lesson.
Select all the correct answers.
Don't confuse RAG with grounding with Google Search
Grounding with Google Search connects Gemini to the live public web for current facts with citations. Your handbook is private, so Search grounding will not find it. You enable Search grounding as a tool. For your own files, use File Search or your own embeddings. When a query needs both public facts and internal policy, use both.
Scaling up: vertex AI RAG engine
When you need enterprise controls such as data residency, IAM, audit logging, or VPC security, move to Vertex AI, Google Cloud's managed AI platform. Its RAG Engine handles chunking, embedding, storage, and retrieval over corpora in Cloud Storage or Drive. It also lets you choose your vector database. Start at cloud.google.com/vertex-ai.
Rough rule of thumb:
- Managed RAG with minimal setup: the Gemini API File Search tool.
- Custom ranking or your own database:
gemini-embedding-001plus your vector store. - Production with compliance needs: Vertex AI RAG Engine.
- Agentic retrieval inside a larger workflow: wrap retrieval as a tool in the Agent Development Kit (ADK), so an agent can decide when to search the handbook and when to search the web.
The no-code path: where your handbook already lives
If the handbook is a Google Doc in a shared Drive, you may not need a pipeline at all:
- A Gem (a custom, reusable Gemini configuration) can take the handbook as a reference file plus an instruction like "answer HR questions citing the policy section." Setup is at support.google.com.
- Gemini in Google Workspace can reason over Drive files from the side panel, using "@" to reference files.
- Apps Script lets you call the Gemini API from inside Workspace. For example, a Sheet could classify support tickets against handbook categories.
A Gem may solve in five minutes what you were about to spend a week coding.
A practical decision flow
When someone says "make our handbook answerable," ask:
- One document, occasional use? Use the File API.
- A few dozen docs, and you want it working this afternoon? Use File Search.
- Need custom chunking, hybrid search, or your own database? Build your own embeddings pipeline.
- Production with compliance requirements? Use Vertex AI RAG Engine.
- Non-technical owner, and the doc is already in Drive? Use a Gem or the Workspace side panel.
- Needs public web facts too? Add grounding with Google Search.
Key Takeaways
- Try long context before RAG. If the corpus fits the window, the File API gives accurate answers with little code.
- The Gemini API File Search tool is now the fastest route to managed RAG: upload to a store, pass it as a tool, and get citations back.
- Build your own pipeline with
gemini-embedding-001only when you need control. Settask_typeon every call:RETRIEVAL_DOCUMENTfor chunks,RETRIEVAL_QUERYfor questions. - Guard against hallucination in the prompt by telling Gemini to answer only from retrieved excerpts and to say when the answer is absent.
- Grounding with Google Search covers public facts, not your private files. Move to Vertex AI RAG Engine when compliance requires it, and try a Gem first when the users are non-technical.
What to do, from this lesson
These actions are compiled in the role's Playbook.
- Stuff single large artifacts into long context, reserving RAG for large corpora