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.

Three retrieval strategies, ranked by effort

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 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 → is large enough to 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. 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 window, 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. Reach for embeddings when scale or cost forces you to.

Strategy 1: Just upload the file

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 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 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.

When long context stops being enough

Long context is wonderful until it isn't. Three signals tell you to move to real RAG:

• The corpus exceeds the window. Fifty handbooks, a wiki export, years of policy memos. You cannot inline all of it.
• 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 →. Sending the entire handbook on every one 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."

This is where embeddings earn their place.

Strategy 3: embeddings and true RAG

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 embedding model is gemini-embedding-001, available through the same Gemini API. One important detail: it supports a task type parameter. You tell it whether you are embedding 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.

Step 1: Chunk and embed your documents

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"},
).embeddings

In 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).

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]]

Note the task_type difference: documents were embedded as RETRIEVAL_DOCUMENT, the question as RETRIEVAL_QUERY. Same model, asymmetric roles.

Step 3: Generate a grounded answer

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 guardrailguardrailRules and controls that keep an AI system inside safe, legal and on-brand boundaries, blocking outputs and actions that cross the line.View full definition → against hallucination. RAG does not stop a model from inventing answers; the prompt discipline does.

Don't confuse RAG with grounding with Google Search

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 API; you build the embeddings pipeline above for your own files. Use both when a query needs public facts *and* internal policy.

Scaling up: vertex AI and managed RAG

Everything above runs on the Gemini API 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 pipeline that handles chunking, embedding, 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:

• Prototype or personal tool: Gemini API + your own vector store (the code above).
• 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 versus the web.

The no-code path: where your handbook already lives

Not every "answer from our handbook" problem needs a pipeline. If your handbook is a Google Doc in a shared Drive, you have lighter options:

• A Gem (a custom, reusable Gemini configuration) can be given the handbook as reference and a fixed instruction like "answer HR questions citing the policy section." Non-technical colleagues get a tuned assistant with zero code. See support.google.com for setup.
• Gemini in Google Workspace can reason over files in Drive and answer in Docs or Gmail directly, using the "@" file referencing in the side panel.
• For something more custom but still no infrastructure, Apps Script lets you call the Gemini API from inside Workspace, for example a Sheet that classifies support tickets against handbook categories.

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.

A practical decision flow

When someone says "make our handbook answerable," ask:

1. One document, occasional use? Upload it. File API. 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.

Key Takeaways

• Try long context before RAG. If the corpus fits the window, the File API gives more accurate answers with far less code. Only build embeddings when scale, cost, or provenance forces you to.
• Set `task_type` on every embedding call: RETRIEVAL_DOCUMENT for stored chunks, RETRIEVAL_QUERY for the question. This single parameter visibly improves retrieval.
• Guard against hallucination in the prompt, not the pipeline: instruct Gemini to answer only from the retrieved excerpts and to say when the answer is absent.
• Grounding with Google Search is not private RAG. Use it for live public facts; build embeddings for your own files; combine them when a query needs both.
• Graduate to Vertex AI RAG Engine for production, and consider a Gem or Workspace side panel when the real requirement is "non-technical colleagues, document already in Drive."