How to create a retriever in LlamaIndex

Retrieval-augmented generation separates source matching from the language model that writes an answer. In LlamaIndex, creating a retriever directly from an index lets an application inspect the selected nodes and their metadata without adding response synthesis.

The index.as_retriever() method returns a retriever backed by that index. Calling retrieve() produces NodeWithScore objects, which carry each matched node, its metadata, and its similarity score when the backing store supplies one.

A local MockEmbedding keeps the check independent of API keys, but its fixed vectors make this a wiring test rather than a ranking evaluation. Use the application's embedding model when comparing relevance across multiple documents.

1. Activate the .venv Python environment that contains llama-index-core.

   $ source .venv/bin/activate

   Related: How to install LlamaIndex with pip

2. Start retriever_check.py with the retriever dependencies.

   retriever_check.py

   from llama_index.core import Document, MockEmbedding, VectorStoreIndex
   from llama_index.core.schema import NodeWithScore

3. Add the local document fixture after the import block.

   retriever_check.py

   documents = [
       Document(
           text=(
               "The Atlas support playbook says refund escalations must include "
               "the order ID, customer tier, and billing owner."
           ),
           metadata={"source": "atlas-support-playbook"},
       )
   ]

   The single document isolates the index-to-retriever handoff from multi-document ranking behavior.

4. Build the vector index after the document fixture.

   retriever_check.py

   index = VectorStoreIndex.from_documents(
       documents,
       embed_model=MockEmbedding(embed_dim=8),
   )

   The mock embedding keeps index construction local and requires no API key.
   Related: How to set an embedding model in LlamaIndex

5. Create the retriever after the index definition.

   retriever_check.py

   retriever = index.as_retriever(similarity_top_k=1)

   The similarity_top_k value limits retrieval to one node.
   Related: How to set retriever similarity top K in LlamaIndex

6. Retrieve the matching node after the retriever definition.

   retriever_check.py

   results = retriever.retrieve("What must a refund escalation include?")
   first = results[0]

7. Add fail-capable outcome checks after the retrieval block.

   retriever_check.py

   assert len(results) == 1
   assert isinstance(first, NodeWithScore)
   assert first.node.metadata["source"] == "atlas-support-playbook"
   assert "order ID, customer tier, and billing owner" in first.node.get_content()

8. Print the retriever and matched node fields after the assertions.

   retriever_check.py

   print(f"retriever_type={type(retriever).__name__}")
   print(f"result_type={type(first).__name__}")
   print(f"source={first.node.metadata['source']}")
   print(f"text={first.node.get_content()}")

9. Run the completed retriever script.

   $ python retriever_check.py
   retriever_type=VectorIndexRetriever
   result_type=NodeWithScore
   source=atlas-support-playbook
   text=The Atlas support playbook says refund escalations must include the order ID, customer tier, and billing owner.