> ## Documentation Index
> Fetch the complete documentation index at: https://docs.naga.ac/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieval Patterns

> Use the Embeddings API in practical retrieval and ranking workflows.

Use the `Embeddings API` when you want retrieval, semantic search, ranking, or a RAG pipeline.

## Typical retrieval flow

<Steps>
  <Step title="Chunk the source material">
    Split documents into chunks that are small enough for retrieval but still
    semantically coherent.
  </Step>

  <Step title="Embed the chunks">
    Generate vectors for each chunk using one embedding model.
  </Step>

  <Step title="Store vectors and metadata">
    Keep the embeddings together with metadata such as document ID, title, or
    section so you can filter and cite later.
  </Step>

  <Step title="Embed the user query">
    Use the same embedding model for the query that you used for the indexed
    chunks.
  </Step>

  <Step title="Retrieve nearest chunks">
    Search for the closest matches in vector space.
  </Step>

  <Step title="Filter or rerank if needed">
    Narrow the candidate set before generation when your pipeline needs better
    precision.
  </Step>

  <Step title="Pass the final context into generation">
    Send the selected context to your generation step, usually through
    `Responses API`.
  </Step>
</Steps>

Use `Responses API` for the generation step and `Embeddings API` for the retrieval step.

## Good defaults

* Keep chunks semantically coherent instead of embedding entire long documents.
* Store metadata with each vector so you can filter, cite, or deduplicate later.
* Keep a stable embedding model per index version.
* Retrieve a small candidate set before you generate the final answer.

## Common Pitfalls

* mixing embeddings from different models in one index
* not versioning your embedding model choice
* embedding documents and queries with different incompatible models
* indexing chunks that are too large or too small for your retrieval goals
* skipping evaluation, so retrieval quality degrades without being noticed

## Retrieval checklist

* Choose one embedding model for both documents and queries.
* Re-embed the corpus when you change embedding models.
* Measure retrieval quality on a small set of known-good queries.
* Keep generation and retrieval concerns separate.

## Related Docs

* [Embeddings API](/api/embeddings)
* [Responses API](/api/responses)
* [Batch Inputs](/api/embeddings/batch-inputs)
* [Output Formats](/api/embeddings/output-formats)