AI Agents · Lesson

HyDE: Hypothetical Document Embeddings

Generate a fake 'ideal' answer with the LLM, embed it, and search with that — beats short-query embeddings.

HyDE: Hypothetical Document Embeddings is a free AI Agents lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the AI Agents learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

The Problem with Query Embeddings

User queries are usually short and look nothing like the documents you want to retrieve.

Query: "fix my keyboard"
Doc: "If your mechanical keyboard's keys are sticking, you can clean the switches with isopropyl alcohol..."

The vectors are semantically distant; retrieval misses the doc.

HyDE Idea

HyDE = Hypothetical Document Embeddings (Gao et al. 2022).

Ask the LLM to write a fake "ideal answer" to the query
Embed the fake answer (not the query)
Use that vector to search the real corpus

Why It Works

The hypothetical answer looks like a real document (similar vocabulary, similar structure). Its embedding lives close to the real-document embeddings — so retrieval finds them more reliably.

Implementation

def hyde_search(query, k=5):
    # Step 1: hallucinate an answer
    hypo_answer = llm.invoke(f'Please write a passage to answer the question: {query}').content
    # Step 2: embed it
    vec = embed(hypo_answer)
    # Step 3: retrieve
    return vector_db.query(vec, k=k)

It Is OK That the Answer Is Wrong

HyDE's hypothetical answer might be factually wrong — that's fine. We only use its embedding for retrieval. The retrieved REAL docs are then used to generate the final answer.

Code Example with LangChain

from langchain.chains import HypotheticalDocumentEmbedder
from langchain_openai import OpenAIEmbeddings, ChatOpenAI

embeddings = HypotheticalDocumentEmbedder.from_llm(
    ChatOpenAI(),
    OpenAIEmbeddings(),
    'web_search'   # built-in prompt template
)
vector = embeddings.embed_query('How do I fix a sticky keyboard?')

Cost Trade-off

HyDE costs 1 extra LLM call per query. Worth it when:

Query phrasing is very different from document phrasing
Retrieval recall is your bottleneck
Corpus contains technical writing the user paraphrases

Multi-Sample HyDE

Generate N hypothetical answers, embed each, retrieve top-K for each, and union the results. More expensive but higher recall on tricky queries.

hypos = [llm.invoke(...).content for _ in range(3)]
vecs = [embed(h) for h in hypos]
results = set()
for v in vecs:
    results.update(vector_db.query(v, k=5))

Combining HyDE with Re-ranking

HyDE for recall, cross-encoder for precision:

HyDE retrieves top-50
Cross-encoder reranks to top-5
LLM answers using top-5

When NOT to Use HyDE

Queries already match document language (FAQs)
Latency-critical paths
Very short corpora where naive retrieval works

HyDE for Code

For code-search: hallucinate the function the user is looking for, embed, retrieve real functions.

code_hypo = llm.invoke(f'Write the Python function that does: {user_request}').content
results = code_index.search(embed(code_hypo))

Variants: Step-Back Prompting

Related technique: ask the model to derive a more general question first ("How do I clean keyboards?" -> "What general cleaning method applies to mechanical keyboards?"), embed that, then retrieve.

HyDE Why It Works

What makes HyDE retrieve better than embedding the raw query?

Recap

HyDE: hallucinate an answer, embed THAT, search. Costs one extra LLM call but improves retrieval on hard, paraphrased, or technical queries.

Frequently asked questions

Is the “HyDE: Hypothetical Document Embeddings” lesson free?

Yes — the full text of “HyDE: Hypothetical Document Embeddings” is free to read here on the web, and the AI Agents course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the AI Agents course, upgrade to CoddyKit PRO.

What will I learn in “HyDE: Hypothetical Document Embeddings”?

Generate a fake 'ideal' answer with the LLM, embed it, and search with that — beats short-query embeddings. You practise AI Agents with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start AI Agents?

No prior experience is required. AI Agents on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “HyDE: Hypothetical Document Embeddings” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this AI Agents lesson?

Yes. Every AI Agents lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to AI Agents