Blog260905 | Understanding LlamaIndex Architecture Through a RAG Application

01 / architecture

LlamaIndex is not a vector database. It is the data orchestration layer for RAG.

In this demo, LlamaIndex works across two layers. At the upper layer, business data becomes a consistent set of data objects. At the lower layer, those objects are connected to an embedding model, vector storage, and an LLM. PostgreSQL + pgvector handles storage and similarity search. DeepSeek generates the natural-language answer. LlamaIndex connects them into a reliable data pipeline.

The raw movie records are not handed directly to the LLM. They first become Documents, then TextNodes. VectorStoreIndex triggers embedding generation, while StorageContext connects the indexing process to PGVectorStore. The result is persisted in PostgreSQL + pgvector.

When a user asks a question, QueryEngine embeds the query, uses pgvector to find the closest TextNodes, and sends those retrieved contexts to the LLM for answer generation.

The LLM is not the component that searches the database. It reads the retrieved material and explains it. The embedding retrieval stage is what narrows the information space.

ingest

movies.json->Document->TextNode->embedding

index

VectorStoreIndex->StorageContext->PGVectorStore

storage

PostgreSQL+pgvector->data_movie_rag

query

QueryEngine->Top-K TextNodes->DeepSeek answer

02 / objects

These six concepts are not isolated terms. They form a handoff path.

Put them back into the demo's execution order and the architecture becomes much easier to read: Document is the input shape, TextNode is the retrieval unit, VectorStoreIndex is the indexing executor, StorageContext routes data to storage, PGVectorStore is the PostgreSQL adapter, and QueryEngine is the query-facing entry point.

Input object Document

A movie record from JSON becomes text + metadata. It preserves business meaning and enters LlamaIndex in a standard shape.

Retrieval unit TextNode

The Document becomes a node with a node_id. Embedding, retrieval, and context references all happen around this node.

Index executor VectorStoreIndex

During ingestion it creates node vectors; during querying it restores a searchable index view from an existing vector store.

Storage wiring StorageContext

It connects the indexing process to a chosen backend and tells LlamaIndex where nodes, metadata, and vectors should go.

Vector storage PGVectorStore

It persists LlamaIndex nodes into PostgreSQL + pgvector and forms the data_movie_rag table.

Query entry QueryEngine

It receives the user question, retrieves Top-K TextNodes, and sends the context to DeepSeek for answer generation.

Ingestion path Document -> TextNode -> embedding -> PGVectorStore turns six movies into six reusable vector records.

Storage relationship StorageContext does not store the movie content itself. It connects VectorStoreIndex to PostgreSQL as the persistent backend.

Query path QueryEngine reuses the existing index: the question is embedded, Top-3 nodes are retrieved, and the LLM synthesizes the answer.

03 / ingestion

Ingestion: turning six movies into six searchable nodes

The goal of ingestion is not to answer a question. It prepares knowledge so questions can be answered later. In this demo, six Chinese movie records become Document objects, then TextNode objects. Each node receives a 512-dimensional embedding and is written to PostgreSQL.

Business data

movies.jsontitle, genre, keywords, summary

Text assemblyExpose complete meaning to retrieval

metadataKeep title / genre

6 moviesThe Martian, Interstellar, and more

LlamaIndex

DocumentStandard input container

TextNodeRetrieval and citation unit

VectorStoreIndexCreate the index and batch insert

StorageContextBind the storage backend

Storage and models

Hugging Facebge-small-zh-v1.5

PGVectorStorePostgreSQL adapter

pgvectorvector(512) similarity search

data_movie_rag6 node records

Document(
  text="""
Title: The Martian
Genre: Science Fiction
Keywords: Mars, astronaut, survival science, engineering, rescue
Summary: An astronaut is stranded on Mars and survives
through botany, engineering, and a rescue plan.
""",
  metadata={
    "title": "The Martian",
    "genre": "Science Fiction"
  }
)

vector_store = PGVectorStore.from_params(
  database=settings.db_name,
  host=settings.db_host,
  port=settings.db_port,
  user=settings.db_user,
  password=settings.db_password,
  table_name=settings.pgvector_table,
  embed_dim=512
)

storage_context = StorageContext.from_defaults(
  vector_store=vector_store
)

VectorStoreIndex.from_documents(
  documents,
  storage_context=storage_context,
  show_progress=True
)

04 / query

Query flow: how QueryEngine turns a question into an evidence-based answer

The query stage does not ingest the six movies again. It connects to the existing PGVectorStore. VectorStoreIndex.from_vector_store(...) creates a queryable index view, and index.as_query_engine(similarity_top_k=3) becomes the user-facing query interface.

When the user asks for "space science fiction, ideally with astronauts, Mars, or interstellar travel," QueryEngine first sends the question through the same embedding model and creates a query vector. PGVectorStore then lets PostgreSQL run similarity search over data_movie_rag.embedding and return the three closest TextNodes.

The boundary matters: pgvector returns relevant nodes, while DeepSeek turns those nodes into a natural-language recommendation. The LLM is not scanning the database. It is expressing an answer based on retrieved context.

index = VectorStoreIndex.from_vector_store(
  vector_store=vector_store
)

query_engine = index.as_query_engine(
  similarity_top_k=3
)

response = query_engine.query(
  "I want a space sci-fi movie, preferably with astronauts, Mars, or interstellar travel."
)

Top 1

The Martian

Directly matches Mars, astronauts, scientific survival, and rescue. It is the closest node to the user's intent.

Top 2

Interstellar

Matches interstellar travel, astronauts, wormholes, and black holes. It strongly fits the space exploration intent.

Top 3

The Wandering Earth

Fits the broader theme of space science fiction and humanity's future, though it is less directly tied to Mars or astronauts.

05 / storage

From the database's point of view, RAG is not mysterious. It is an inspectable table.

The demo starts a PostgreSQL container from the pgvector/pgvector:pg16 image and enables the vector extension. The database check script sees vector 0.8.6 and verifies vector distance calculation with the <-> operator.

Field or object	Source	Why it matters in RAG
`text`	`TextNode.text`	This is the context the LLM eventually reads and cites. The embedding alone cannot explain the movie; the text is the evidence.
`metadata_`	`Document.metadata` passed to `TextNode`	Stores title, genre, document_id, ref_doc_id, and related information for source display, filtering, and governance.
`node_id`	Created by LlamaIndex	Lets the system track each retrieval unit for updates, deletion, citation, deduplication, and source linking.
`embedding`	Hugging Face embedding model	A 512-dimensional semantic vector. pgvector uses it to compute distance between the question and each node.
`PGVectorStore`	LlamaIndex vector store integration	Writes LlamaIndex nodes to PostgreSQL and turns similarity search results back into LlamaIndex-compatible nodes.

06 / principles

The real takeaway is component boundaries

This demo contains only six movies, but it shows a division of responsibility that can scale to real systems: data objects, indexing, storage, retrieval, and generation each handle one part of the pipeline and connect through clear interfaces.

Document brings data into the system. TextNode defines the retrieval grain. VectorStoreIndex builds the index. StorageContext routes writes to the storage backend. PGVectorStore persists vectors in PostgreSQL. QueryEngine turns a question into an answer with context.

Do not reduce RAG to a prompt. Before the prompt, there is data preparation, node splitting, vectorization, persistence, and retrieval.
Embeddings find similarity; the LLM explains. Separating those jobs makes the answer easier to control.
StorageContext is where replaceability comes from. If you switch to another vector store, the indexing logic does not need to be rewritten from scratch.
Metadata is the governance entry point. In production, permissions, sources, domains, and time ranges are often enforced through metadata filters.
Top-K is a retrieval quality knob. The demo uses 3 for clarity; real systems tune it against noise, context length, and answer quality.

One-sentence summary

This is a learning-oriented RAG demo: Docker starts PostgreSQL + pgvector, Hugging Face embeddings turn Chinese movie text into vectors, LlamaIndex orchestrates ingestion and query flows, and DeepSeek generates Chinese movie recommendations from the retrieved results.