How do you keep LlamaIndex metadata out of embeddings while the LLM still sees it?

## The behaviour people miss A LlamaIndex node is not embedded as `node.text`. It is embedded as a rendering of metadata plus text. Load a folder with `SimpleDirectoryReader` and every node quietly carries `file_path`, `file_name`, `file_type`, `file_size`, `creation_date` and `last_modified_date` — and by default those strings sit in front of the chunk text when the embedding is computed and when the chunk is placed in the prompt. On a 1,000-token chunk that is noise you can absorb. On a 128-token chunk it can be a third of the tokens, and the embedding drifts toward "this is a file from a directory" and away from the sentence's meaning. Symptoms are recognisable: chunks from the same directory cluster together regardless of topic, similarity scores compress into a narrow band, and short chunks retrieve worse than long ones. ## The controls Four fields on every `Document`/`TextNode`: - `excluded_embed_metadata_keys: list[str]` — keys omitted when building the text to embed. - `excluded_llm_metadata_keys: list[str]` — keys omitted when building the text shown to the LLM. - `metadata_template` — how one key/value pair is rendered, e.g. `"{key}: {value}"`. - `metadata_seperator` — what joins the rendered pairs (note the spelling in the library). Plus `text_template`, which controls how the rendered metadata block and the content are combined. The two exclusion lists are independent, and that independence is the whole point. A key can be: - **In both renderings** — a document title or section heading. Genuinely semantic, helps the embedding, and helps the model know what it is reading. - **Embed-excluded, LLM-visible** — a source URL or filename. Useless as embedding signal, essential when you want the model to cite where an answer came from. - **Excluded from both** — internal ids, byte sizes, ingestion timestamps, tenant keys. Still stored, still available for metadata filtering at retrieval time, invisible to both models. Exclusion never removes metadata from storage. Filtering at query time reads the stored `metadata` dict, so a fully excluded key still works perfectly as a filter. ## Verifying it ``` from llama_index.core.schema import MetadataMode print(node.get_content(metadata_mode=MetadataMode.EMBED)) print(node.get_content(metadata_mode=MetadataMode.LLM)) ``` This is the highest-value five-line diagnostic in a LlamaIndex ingestion review, and hardly anyone runs it. `MetadataMode.ALL` shows everything, `MetadataMode.NONE` shows bare text. Printing the EMBED rendering of a handful of real nodes tells you immediately how much of each chunk's embedding budget is going to bookkeeping. ## Where to set it Set the exclusion lists on the **Document**, at ingestion time. Node parsing copies metadata and the exclusion lists onto every node produced from that Document, so one assignment covers the whole file. Setting them per node after parsing works but is error-prone and easy to apply inconsistently across sources. If a metadata extractor adds keys later — a generated title, a summary, extracted questions — decide the visibility of those keys explicitly too. An extracted summary is usually worth embedding; extraction bookkeeping is not. ## Second-order effects - **Token budget.** Metadata counts toward the chunk's tokens in the prompt. Ten retrieved chunks each carrying five metadata lines is a real slice of the context window spent on file paths. - **Reranking.** A cross-encoder reranker also scores the rendered text, so metadata noise degrades the second stage as well as the first. - **Re-embedding.** Changing what is embedded changes the vectors. Adjusting exclusion lists on an existing corpus means re-embedding it, and mixing old and new renderings in one store makes similarity comparisons quietly inconsistent — decide the policy before the first large ingest. - **Leakage.** Anything LLM-visible can be reproduced in an answer. Internal paths, employee ids and tenant identifiers belong in `excluded_llm_metadata_keys` for reasons that are about disclosure, not retrieval quality. ## The rule of thumb Ask of each key: would a human searching for this passage type these words? If yes, embed it. Would the model need it to answer or to cite? If yes, show it. Otherwise store it, filter on it, and hide it from both.