# Files, embeddings, and RAG with Google
You can hand Gemini a 200-page employee handbook and 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 three 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.
Before any code, get the decision right. On Google AI you have three distinct approaches, and people waste weeks building the wrong one.
1. Long context (stuff the file in the prompt). Gemini's context windowcontext window is large enough to hold entire documents. For a single handbook, you may not need RAG at all. Upload, ask, done.
2. The File API. For files too big to inline, or that you reuse across many requests, upload once and reference the handle. Still long-context retrieval, just managed better.
3. Embeddings + a vector store (true RAG). When you have hundreds of documents, or need to retrieve across a corpus that exceeds the 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 →, you embed chunks, store the vectors, and retrieve the relevant ones per query.
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. 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 embeddings when scale or cost forces you to.
In Google AI Studio, drag your handbook PDF into a prompt and ask. Native multimodality means Gemini reads the PDF directly, including tables and layout, no OCR step.
For the APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition →, small files can be sent inline as bytes. But the moment a file is large, or you will ask many questions against it, use the File APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → instead.
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 each time. Uploaded files are retained for a limited period (currently around 48 hours) and are free to store, which makes this ideal 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. Flash is the right tier here: fast, cheap, and more than capable of reading one PDF. Save Pro for harder reasoning over messy, multi-document inputs.
The official guide for upload limits and supported types lives at ai.google.dev. Check it rather than guessing at size caps, which change.
Long context is wonderful until it isn't. Three signals tell you to move to real RAG:
This is where embeddings earn their place.
You already know the RAG concept. Here is how it maps to Google's specific tools.
An 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 → is a vector (a list of numbers) that captures the meaning of a chunk of text, so that semantically similar chunks sit near each other in vector space. You embed your document chunks once, store the vectors, embed the user's question at query time, and retrieve the nearest chunks to feed into Gemini.
Google's current 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 → model is gemini-embedding-001, available through the same Gemini APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition →. One important detail: it supports a task type parameter. You tell it whether you are 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 → a document for storage (RETRIEVAL_DOCUMENT) or a query for searching (RETRIEVAL_QUERY). Setting this correctly meaningfully improves retrieval quality, and skipping it is the most common mistake.
Split the handbook into sections (by heading is ideal), then embed each chunk as a document.
from google import genai
client = genai.Client()
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...",
# ...one entry per handbook section
]
doc_vectors = client.models.embed_content(
model="gemini-embedding-001",
contents=chunks,
config={"task_type": "RETRIEVAL_DOCUMENT"},
).embeddingsIn production you store these vectors in 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 →. For a small internal tool, an in-memory list with cosine similarity is genuinely fine. For scale, Vertex AI offers a managed option (more on that below).
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]]Note the task_type difference: documents were embedded as RETRIEVAL_DOCUMENT, the question as RETRIEVAL_QUERY. Same model, asymmetric roles.
Now feed only the retrieved chunks into Gemini. This is the payoff: a tiny, cheap prompt instead of the whole handbook.
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)That "answer using ONLY the excerpts, and say so if absent" instruction is your guardrail against hallucinationhallucinationA hallucination is when an AI model generates output that is fluent and confident but factually wrong, fabricated, or unsupported by its source data.View full definition →. RAG does not stop a model from inventing answers; the prompt discipline does.
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.
A frequent mix-up: grounding with Google Search is not RAG over your private documents. It connects Gemini to the live public web, so the model can answer questions about current events with citations. Your handbook is private and not on the public web, so Search grounding will not help with it. You enable Search grounding as a tool in the APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition →; you build the embeddings pipelinepipelineAll active sales opportunities across the stages of the sales process, together with their combined potential value and probability of closing.View full definition → above for your own files. Use both when a query needs public facts *and* internal policy.
Everything above runs on 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 → and is perfect for prototypes and internal tools. When you need enterprise controls (data residency, IAM, scale, audit logging), move to Vertex AI, Google Cloud's managed AI platform.
Vertex offers RAG Engine, a managed pipelinepipelineAll active sales opportunities across the stages of the sales process, together with their combined potential value and probability of closing.View full definition → that handles chunking, 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 →, vector storage, and retrieval for you. You point it at a corpus in Cloud Storage or Drive, and it returns grounded responses. You write far less plumbing, and you get the governance that a security team will ask about. Start at cloud.google.com/vertex-ai.
Rough rule of thumb:
Not every "answer from our handbook" problem needs a pipelinepipelineAll active sales opportunities across the stages of the sales process, together with their combined potential value and probability of closing.View full definition →. If your handbook is a Google Doc in a shared Drive, you have lighter options:
The lesson: match the tool to the user and the scale. A Gem may solve in five minutes what you were about to spend a week coding.
When someone says "make our handbook answerable," ask:
1. One document, occasional use? Upload it. File APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition →. Done.
2. A few docs, technical owner, prototype? Embeddings + in-memory similarity (the code above).
3. Many docs, production, compliance? Vertex AI RAG Engine.
4. Non-technical owner, doc in Drive? A Gem or Workspace side panel.
5. Needs public web facts too? Add grounding with Google Search.
RETRIEVAL_DOCUMENT for stored chunks, RETRIEVAL_QUERY for the question. This single parameter visibly improves retrieval.These actions are compiled in the role's Playbook.