【LlamaIndex核心组件指南 | Prompt篇】深度解析LlamaIndex提示模板的设计与实战

Langchain系列文章目录

01-玩转LangChain：从模型调用到Prompt模板与输出解析的完整指南
02-玩转 LangChain Memory 模块：四种记忆类型详解及应用场景全覆盖
03-全面掌握 LangChain：从核心链条构建到动态任务分配的实战指南
04-玩转 LangChain：从文档加载到高效问答系统构建的全程实战
05-玩转 LangChain：深度评估问答系统的三种高效方法（示例生成、手动评估与LLM辅助评估）
06-从 0 到 1 掌握 LangChain Agents：自定义工具 + LLM 打造智能工作流！
07-【深度解析】从GPT-1到GPT-4：ChatGPT背后的核心原理全揭秘
08-【万字长文】MCP深度解析：打通AI与世界的“USB-C”，模型上下文协议原理、实践与未来

Python系列文章目录

PyTorch系列文章目录

机器学习系列文章目录

深度学习系列文章目录

Java系列文章目录

JavaScript系列文章目录

Llamaindex系列文章目录

01-【LlamaIndex核心组件指南 | 模型篇】一文通晓 LlamaIndex 模型层：LLM、Embedding 及多模态应用全景解析
02-【LlamaIndex核心组件指南 | Prompt篇】深度解析LlamaIndex提示模板的设计与实战

---

---

前言

在人工智能技术快速发展的背景下，大语言模型（LLM）虽然能力强大，但其知识往往局限于训练数据，无法直接访问我们私有的、实时的外部数据源。如何安全、高效地将 LLM 与我们的数据连接起来，构建强大的检索增强生成（RAG）应用，已成为开发者的核心议题。LlamaIndex正是为解决这一问题而生的。

LlamaIndex 是一个领先的开源数据框架，旨在帮助开发者轻松构建、优化和部署基于自定义数据的 LLM 应用。通过 LlamaIndex，开发者可以无缝集成数据加载、索引构建、查询引擎、响应合成等一系列复杂功能，极大地简化了 RAG 应用的开发流程。

LlamaIndex 的核心组件

LlamaIndex 由一系列高度模块化的组件构成，每个组件都专注于 RAG 流程中的特定任务：

1. Loading (数据加载)

   • 提供数百个数据连接器（Data Connectors），用于从各种来源（如本地文件、Notion、数据库、API）摄取数据。
   • 将加载的数据统一转换为标准的 Document 对象，便于后续处理。

2. Indexing (索引构建)

   • 负责将非结构化或结构化的 Document 数据转换为 LLM 能够高效查询的数据结构（即索引）。
   • 支持多种索引类型，如向量存储索引 (VectorStoreIndex)、知识图谱索引 (PropertyGraphIndex)等。

3. Storing (持久化存储)

   • 管理数据和索引的持久化，确保应用的可扩展性和状态保持。
   • 包含文档存储 (Docstore)、索引存储 (IndexStore)和向量存储 (VectorStore)三大组件。

4. Querying (查询引擎)

   • 是 RAG 的核心执行者，接收用户查询，并从索引中检索相关信息。
   • 通过响应合成 (Response Synthesis)模块将检索到的上下文和用户查询整合，生成最终答案。

5. Models (模型)

   • 提供与各种大语言模型 (LLMs)、嵌入模型 (Embeddings)和多模态模型 (Multi-modal Models)交互的统一接口。
   • 是驱动整个应用理解、表示和生成信息的大脑。

6. Agents (智能体)

   • 赋予 LLM 超越简单问答的能力，使其能够使用外部工具（如 API 调用、数据库查询）来执行多步骤的复杂任务。
   • 是构建自动化工作流和实现更高级别自主性的关键。

LlamaIndex 的应用场景

LlamaIndex 的模块化和 RAG 专注设计使其在以下场景中表现出色：

• 智能问答与知识库：构建基于海量私有文档（PDF、Word、Notion）、数据库或企业知识图谱的智能问答机器人。
• 文档理解与摘要：对大量、复杂的非结构化文档进行深度分析、信息提取和自动化摘要。
• 结构化数据分析：连接到 SQL 或图数据库，用自然语言查询结构化数据并获得分析结果。
• 自主研究智能体：创建能够主动查询外部数据源、执行代码、并综合信息生成研究报告的自动化智能体。
• 多模态 RAG 应用：构建能够同时理解文本和图像内容，并基于图文信息进行问答的应用。

本文主题

在构建基于大语言模型（LLM）的应用程序，特别是检索增强生成（RAG）系统时，LlamaIndex 无疑是当今最强大、最灵活的框架之一。它通过一系列高度模块化和可扩展的组件，极大地简化了从数据加载、索引、检索到响应生成的整个流程。

本文将从整个框架的“神经中枢”——提示（Prompts）——开始。Prompt 是我们与 LLM 沟通的桥梁，其设计的优劣直接决定了模型响应的质量。本文将基于 LlamaIndex 的官方文档，结合结构化的重组和深度解读，带您全面了解 LlamaIndex 中 Prompt 的设计哲学、核心组件、实战技巧与高级用法，助您精准驾驭 LLM，释放其全部潜能。

---

一、LlamaIndex 核心组件概览

在深入探讨 Prompt 之前，我们有必要先对 LlamaIndex 的整体架构有一个宏观的认识。LlamaIndex 的设计哲学是“分而治之”，将一个复杂的 RAG 流程拆解为一系列定义明确、可独立配置和替换的组件。

下图展示了 LlamaIndex 的主要组件及其相互关系：

从图中可以看出，Prompts 组件贯穿了索引构建、数据检索和最终答案合成等多个关键环节，是驱动 LLM 在各个阶段执行特定任务的指令核心。理解并精通 Prompt 的使用，是掌握 LlamaIndex 的关键第一步。

核心类别	主要组件	核心功能
Models	LLMs, Embeddings, Multi Modal	封装语言模型、嵌入模型以及多模态模型接口。
Prompts	PromptTemplate, RichPromptTemplate	（本文核心） 管理和格式化提交给 LLM 的指令。
Loading	Data Connectors, Node Parsers	从不同数据源加载数据，并将其解析为标准的 Document 和 Node 结构。
Indexing	Vector Store Index, Property Graph Index	将数据 Node 结构化，创建可供高效检索的索引。
Storing	Vector Stores, Document Stores, Index Stores	持久化存储向量、文档和索引元数据。
Querying	Query Engines, Chat Engines, Retrievers	接收用户查询，从索引中检索相关信息，并合成最终答案。
Agents	Agents, Tools, Memory	构建能够使用工具、具备记忆能力的智能体，完成更复杂的任务。
Workflows	Workflows	编排复杂的多步骤 AI 工作流。
Evaluation	Evaluation	提供评估框架和标准数据集，用于测试和优化应用性能。
Observability	Instrumentation	提供监控和调试应用的能力。

二、深入理解提示（Prompts）的核心概念

2.1 什么是 Prompt？为什么它如此重要？

在 LlamaIndex 的世界里，Prompt（提示） 是赋予 LLM 强大表达能力的基础输入。它不仅仅是一段简单的文本，而是一套精心设计的指令，用于指导 LLM 在 RAG 流程的各个阶段执行特定任务，例如：

• 索引构建 (Indexing): 指导 LLM 如何理解和总结文本块。
• 数据插入 (Insertion): 在更新索引时使用。
• 查询过程 (Querying): 在遍历索引、检索上下文时发挥作用。
• 答案合成 (Synthesizing): 指导 LLM 根据检索到的上下文生成最终答案。

特别是在构建智能体（Agentic）工作流时，设计和管理 Prompt 成为开发过程中的核心环节。一个优秀的 Prompt 能够显著提升模型的理解力、相关性和响应质量。

2.2 LlamaIndex 中的提示模板家族

为了简化和规范 Prompt 的管理，LlamaIndex 提供了强大而灵活的提示模板（Prompt Templates）工具。它们允许开发者定义包含变量的模板，然后在运行时动态填充内容。

模板类型	核心特点	语法	推荐场景
RichPromptTemplate	最新、最强大。支持变量、逻辑（如循环）、对象解析等。	Jinja2	所有新项目，特别是需要复杂逻辑、多模态或动态提示构建的场景。
PromptTemplate	传统、简单。基于单个 f-string。	f-string	维护旧项目或实现非常简单的文本补全（completion）提示。
ChatPromptTemplate	传统、简单。专门用于构建基于消息列表的聊天提示。	f-string	维护旧项目或构建简单的、角色明确的聊天（chat）提示。

LlamaIndex 内置了一套开箱即用的默认 Prompt 模板，在大多数情况下表现良好。但为了实现更精细的控制和优化，强烈建议开发者学习如何自定义模板。最佳实践是从官方默认模板出发，复制其内容，然后在此基础上进行修改。

三、提示模板（Prompt Templates）实战指南

接下来，我们将通过具体的代码示例，展示如何使用 LlamaIndex 中不同类型的提示模板。

3.1 新一代模板：RichPromptTemplate 与 Jinja2 语法

RichPromptTemplate 利用 Jinja2 模板引擎的强大功能，让 Prompt 的构建超越了简单的变量替换，引入了编程逻辑。

3.1.1 基础用法

最显著的变化是，变量从 f-string 的单大括号 {} 变为 Jinja2 的双大括号 {{ }}。

from llama_index.core.prompts import RichPromptTemplate# 定义一个包含上下文和查询变量的 Jinja2 模板字符串
template_str = """我们提供了以下上下文信息：
---------------------
{{ context_str }}
---------------------
请根据这些信息，回答以下问题：{{ query_str }}
"""
qa_template = RichPromptTemplate(template_str)# 1. 格式化为标准的文本 prompt (用于 completion API)
prompt = qa_template.format(context_str="上下文信息...", query_str="用户的问题...")
print(prompt)# 2. 轻松转换为消息列表 (用于 chat API)
messages = qa_template.format_messages(context_str="上下文信息...", query_str="用户的问题...")
print(messages)

3.1.2 进阶用法：循环与多模态

Jinja2 的强大之处在于其控制结构（如循环）和过滤器（filters）。下面是一个构建多模态 Prompt 的例子，它同时处理文本和图像。

from llama_index.core.prompts import RichPromptTemplate# 定义一个更复杂的模板
# {% ... %} 用于控制结构，{{ ... }} 用于变量输出
template_str = """
{%- chat role="system" -%}
你是一个智能助手，能够根据提供的图文信息回答问题。
{%- endchat -%}{%- chat role="user" -%}
{% for image_path, text in images_and_texts %}
这是相关的文本描述: {{ text }}
这是对应的图片:
{{ image_path | image }}
{% endfor %}现在，请回答我的问题。
{%- endchat -%}
"""multi_modal_template = RichPromptTemplate.from_template(template_str)# 准备图文数据
image_text_pairs = [("page_1.png", "这是文档的第一页，介绍项目背景。"),("page_2.png", "这是文档的第二页，包含关键架构图。"),
]# 格式化为 chat messages
messages = multi_modal_template.format_messages(images_and_texts=image_text_pairs)
print(messages)

关键特性解析:

• {% chat role="..." %}: 这是 LlamaIndex 特有的块，用于快速定义一个具有特定角色的聊天消息。
• {% for ... %}: Jinja2 的标准循环语法，用于遍历传入的 images_and_texts 列表。
• {{ image_path | image }}: 这里的 | image 是一个过滤器 (filter)，它向 LlamaIndex 表明 image_path 变量应被特殊处理，格式化为图像内容块，这对于多模态模型至关重要。

3.1.3 结合 Retriever 构建动态上下文

在真实的 RAG 应用中，上下文通常由 Retriever 动态检索而来。

from llama_index.core.prompts import RichPromptTemplate
# 假设 retriever 已经配置好
# from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
# documents = SimpleDirectoryReader("your_data_directory").load_data()
# index = VectorStoreIndex.from_documents(documents)
# retriever = index.as_retriever()template_str = """
{%- chat role="system" -%}
你是一个乐于助人的问答机器人。请严格根据下面提供的上下文来回答问题。
{%- endchat -%}{%- chat role="user" -%}
上下文信息如下：
{% for node in nodes %}
---
{{ node.text }}
---
{% endfor %}我的问题是：{{ query_str }}
{%- endchat -%}
"""template = RichPromptTemplate(template_str)# 假设 retriever.retrieve() 返回一个 Node 列表
# nodes = retriever.retrieve("月球的首都是哪里?")
# 假设返回的 nodes 是一个包含相关文档块的列表# 格式化消息
# messages = template.format_messages(nodes=nodes, query_str="月球的首都是哪里?")
# print(messages)

3.2 传统 f-string 模板的使用

尽管 RichPromptTemplate 是首选，但了解传统的 f-string 模板对于维护旧代码或处理简单场景仍然有帮助。

3.2.1 PromptTemplate：构建完成式提示

from llama_index.core import PromptTemplate# 定义一个标准的 f-string 格式化字符串
template = ("我们提供了以下上下文信息：\n""---------------------\n""{context_str}\n""\n---------------------\n""请根据这些信息，回答以下问题：{query_str}\n"
)
qa_template = PromptTemplate(template)# 格式化为文本 prompt
prompt = qa_template.format(context_str="上下文...", query_str="问题...")
print(prompt)

3.2.2 ChatPromptTemplate：构建对话式提示

from llama_index.core import ChatPromptTemplate
from llama_index.core.llms import ChatMessage, MessageRole# 定义一个由 ChatMessage 对象组成的列表
message_templates = [ChatMessage(content="你是一个专业的系统，请始终保持严谨。", role=MessageRole.SYSTEM),ChatMessage(content="请为我生成一个关于 {topic} 的短篇故事。",role=MessageRole.USER,),
]
chat_template = ChatPromptTemplate(message_templates=message_templates)# 格式化为消息列表
messages = chat_template.format_messages(topic="星际探索")
print(messages)# 也可以转换为单字符串 prompt
prompt = chat_template.format(topic="星际探索")
print(prompt)

四、自定义与管理 Prompt

在复杂的应用中，你可能需要针对不同的模块或查询类型使用不同的 Prompt。LlamaIndex 提供了一套清晰的机制来获取和更新 Prompt。

4.1 如何定位和获取 Prompt？

LlamaIndex 中的许多高级模块（如 Query Engine）是其他子模块的组合。为了方便管理，你可以使用 get_prompts() 方法来获取一个模块及其所有嵌套子模块中使用的全部 Prompt。

# 假设 index 已经创建
# query_engine = index.as_query_engine(response_mode="compact")
#
# # 获取查询引擎中使用的所有 prompts
# prompts_dict = query_engine.get_prompts()
#
# # 打印 prompts 的键名
# print(list(prompts_dict.keys()))
#
# # 可能的输出:
# # ['response_synthesizer:text_qa_template', 'response_synthesizer:refine_template']

注意，键名通常会带有命名空间前缀（如 response_synthesizer:），以表明该 Prompt 所属的子模块，避免命名冲突。

4.2 如何更新和替换 Prompt？

获取到 Prompt 的键名后，就可以使用 update_prompts() 方法来传入自定义的模板。

4.2.1 通用方法：update_prompts

这是一个非常灵活的方法，适用于任何实现了 get_prompts 的模块。

from llama_index.core.prompts import RichPromptTemplate# 假设我们想让 LLM 用莎士比亚的风格回答问题
qa_prompt_tmpl_str = ("上下文信息在下方。\n""---------------------\n""{{ context_str }}\n""---------------------\n""请基于以上上下文信息而非先验知识，""用莎士比亚戏剧的风格回答以下问题。\n""问题: {{ query_str }}\n""答案: "
)
qa_prompt_tmpl = RichPromptTemplate(qa_prompt_tmpl_str)# 假设 query_engine 已创建
# 使用之前获取到的 key 来更新指定的 prompt
# query_engine.update_prompts(
#     {"response_synthesizer:text_qa_template": qa_prompt_tmpl}
# )

4.2.2 Query Engine 中的快捷方式

对于最常用的查询引擎，LlamaIndex 提供了两种等效的方式来覆盖默认 Prompt，开发者可以根据需求选择。

方式	描述	代码示例	优点	缺点
高层 API	在创建查询引擎时，通过 as_query_engine 的参数直接传入。	query_engine = index.as_query_engine(text_qa_template=custom_qa_prompt)	语法糖，简单快捷。	控制粒度较粗，仅支持部分常用参数。
底层组合 API	分别创建 Retriever 和 Response Synthesizer，在创建 Synthesizer 时传入自定义 Prompt。	synth = get_response_synthesizer(text_qa_template=custom_qa_prompt)<br>query_engine = RetrieverQueryEngine(retriever, synth)	完全控制，可配置所有细节。	代码稍显繁琐。

高层 API 是对底层 API 的封装，为的是简化常见操作。当你需要进行更精细的控制时，就应该使用底层组合 API。

4.3 常用 Prompt 类型解析

在自定义过程中，你会频繁遇到两个核心的 Prompt：

• text_qa_template: 问答模板。用于根据检索到的上下文（context_str）对用户问题（query_str）生成首次答案。
• refine_template: 精炼模板。当检索到的上下文信息过多，无法一次性放入 LLM 的窗口时，或者在 response_mode="refine" 模式下，LlamaIndex 会分块处理。它会基于已有的答案（existing_answer）和新的上下文（context_str），让 LLM 对答案进行修正或补充。

五、探索高级 Prompt 功能

对于追求极致灵活性和强大功能的开发者，RichPromptTemplate 还提供了一些高级特性。

5.1 动态格式化：函数映射 (function_mappings)

你可以将一个函数作为模板变量传入，而不是固定的值。这允许在模板渲染时执行动态逻辑，例如实现动态的少样本（Few-shot）学习。

场景：假设你想在将上下文喂给 LLM 之前，自动为每一段上下文添加项目符号。

from llama_index.core.prompts import RichPromptTemplatedef format_context_with_bullets(**kwargs):"""一个函数，用于将换行符分隔的上下文格式化为带-的列表。"""# kwargs 会接收所有 format 时传入的变量context_list = kwargs["context_str"].split("\n\n")formatted_context = "\n\n".join([f"- {c}" for c in context_list])return formatted_context# 在创建模板时，将 context_str 变量映射到我们的函数
prompt_tmpl = RichPromptTemplate("上下文：\n{{ context_str }}", function_mappings={"context_str": format_context_with_bullets}
)# 当调用 format 时，模板会先调用 format_context_with_bullets 函数
# 函数的返回值将用于填充 {{ context_str }}
prompt_str = prompt_tmpl.format(context_str="第一段上下文。\n\n第二段上下文。")
print(prompt_str)
# 输出:
# 上下文：
# - 第一段上下文。
#
# - 第二段上下文。

5.2 灵活构建：部分格式化 (partial_format)

这个功能允许你分步填充模板变量，非常适合构建需要逐步构建的复杂 Prompt。

from llama_index.core.prompts import RichPromptTemplatetemplate = RichPromptTemplate("{{ foo }} {{ bar }} {{ baz }}")# 第一步：先填充 foo 变量，得到一个部分格式化后的新模板
partial_prompt_tmpl_1 = template.partial_format(foo="你好")# 第二步：基于上一步的模板，填充 bar 变量
partial_prompt_tmpl_2 = partial_prompt_tmpl_1.partial_format(bar="世界")# 最后一步：填充最后一个变量，得到最终的字符串
final_str = partial_prompt_tmpl_2.format(baz="!")
print(final_str) # 输出: 你好 世界 !

5.3 增强兼容性：模板变量映射 (template_var_mappings)

LlamaIndex 的内部组件通常期望特定的模板变量名（如 context_str, query_str）。如果你想复用一个已经存在的、变量名不同的模板字符串，而又不想手动修改它，变量映射就派上用场了。

场景：你有一个模板，它使用 my_context 和 my_query 作为变量，但你想将它用于期望 context_str 和 query_str 的 LlamaIndex 模块中。

from llama_index.core.prompts import RichPromptTemplate# 定义映射关系：LlamaIndex内部名 -> 你的模板中的变量名
template_var_mappings = {"context_str": "my_context", "query_str": "my_query"
}# 你的原始模板字符串
original_template_str = "上下文是：{{ my_context }}，问题是：{{ my_query }}"# 创建模板时传入映射关系
prompt_tmpl = RichPromptTemplate(original_template_str,template_var_mappings=template_var_mappings,
)# 现在，LlamaIndex 的组件在内部调用 .format(context_str=..., query_str=...) 时...
# ...模板会自动将其转换为 .format(my_context=..., my_query=...)
prompt_str = prompt_tmpl.format(context_str="这是上下文", query_str="这是问题")
print(prompt_str) # 输出: 上下文是：这是上下文，问题是：这是问题

六、总结

本文作为【LlamaIndex核心组件指南】系列的开篇，系统性地梳理和深度解析了 Prompt 组件。通过本文的学习，我们应掌握以下核心要点：

1. Prompt 的核心地位：Prompt 是 LlamaIndex 的指令核心，贯穿于数据处理和查询的各个关键阶段，是与 LLM 交互的基石。
2. RichPromptTemplate 是首选：基于 Jinja2 的 RichPromptTemplate 是当前官方推荐的、功能最强大的模板工具，它支持逻辑控制、过滤器和多模态，是开发复杂应用的利器。
3. 掌握自定义流程：熟练运用 get_prompts() 来探查模块所用的提示，并使用 update_prompts() 或模块特定的快捷方式（如 as_query_engine 的参数）来进行灵活的定制，是优化 RAG 性能的关键技能。
4. 善用高级功能提升效率：对于复杂场景，LlamaIndex 提供的函数映射、部分格式化和变量映射等高级功能可以极大地提升开发灵活性和代码的可复用性。

精通 Prompt 的设计与管理，是释放 LlamaIndex 和背后大语言模型全部潜能的第一步，也是最重要的一步。希望本文能为您在 LlamaIndex 的探索之路上提供一份详实可靠的地图。在后续的文章中，我们将继续深入其他核心组件，敬请期待。

---