+190 XP

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 reach for each.

Retrieval strategies, ranked by effort

Before any code, get the decision right. People waste weeks building the wrong one.

  1. Long context (put the file in the prompt). Gemini's context window can hold entire documents. For a single handbook, you may not need RAG at all.
  2. 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.
  3. The File Search tool. This is managed RAG inside the Gemini API. You upload documents to a store, and Gemini retrieves the relevant chunks for you, with citations.
  4. 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.

python
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

Watch on YouTube

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 tokens, 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 database.

python
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 used

Unlike the File API's 48-hour files, documents in a store persist until you delete them. At launch, Google charged for embedding 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 pipeline 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

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

For a small internal tool, an in-memory list with cosine similarity is fine.

Step 2: Embed the query and retrieve

python
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

python
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?

MULTIPLE CHOICE

4. Select ALL scenarios where true RAG (embeddings + a vector store) is the appropriate choice.

Select all the correct answers.

MULTIPLE CHOICE

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-001 plus 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:

  1. One document, occasional use? Use the File API.
  2. A few dozen docs, and you want it working this afternoon? Use File Search.
  3. Need custom chunking, hybrid search, or your own database? Build your own embeddings pipeline.
  4. Production with compliance requirements? Use Vertex AI RAG Engine.
  5. Non-technical owner, and the doc is already in Drive? Use a Gem or the Workspace side panel.
  6. 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-001 only when you need control. Set task_type on every call: RETRIEVAL_DOCUMENT for chunks, RETRIEVAL_QUERY for 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
See the full action playbook →