纪环1. LlamaIndex RichPromptTemplate功能概述
RichPromptTemplate是LlamaIndex框架中的核心提示词模板组件，它为构建高效的大语言模型(LLM)应用提供了结构化提示词管理能力。与基础PromptTemplate相比，RichPromptTemplate通过以下特性显著提升了提示工程效率：
- 多变量插值：支持动态参数注入，实现上下文感知的提示生成
- 模板继承：允许创建模板层级结构，减少重复代码
- 格式控制：内置Markdown/HTML格式渲染选项
- 验证机制：自动检查必填参数和类型约束
在实际项目中，RichPromptTemplate常用于构建：
- 知识库问答系统的查询改写
- 文档摘要生成的指令优化
- 多步骤推理的任务分解
- 数据增强的提示变体生成
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 核心功能深度解析
2.1 动态模板引擎
RichPromptTemplate采用Jinja2风格的模板语法，支持复杂逻辑控制：
python复制from llama_index.prompts import RichPromptTemplate
prompt = RichPromptTemplate(
"""分析以下医疗报告并提取关键指标：
{% for item in report_items %}
- {{ item.metric }}: 正常范围 {{ item.normal_range }}
当前值 {{ item.value }} ({{ "异常" if item.is_abnormal else "正常" }})
{% endfor %}
综合评估：{{ assessment|default("需进一步检查") }}"""
)
# 使用示例
context = {
"report_items": [
{"metric": "白细胞计数", "normal_range": "4-10", "value": 12, "is_abnormal": True},
{"metric": "血红蛋白", "normal_range": "120-160", "value": 135, "is_abnormal": False}
]
}
print(prompt.format(**context))
2.2 类型安全验证
通过Pydantic模型实现参数验证：
python复制from pydantic import BaseModel
from typing import List
class ReportItem(BaseModel):
metric: str
normal_range: str
value: float
is_abnormal: bool
class MedicalPromptInput(BaseModel):
report_items: List[ReportItem]
assessment: str = None
prompt = RichPromptTemplate(
template="...", # 同前例模板
input_cls=MedicalPromptInput # 绑定验证模型
)
# 错误输入会触发ValidationError
invalid_context = {"report_items": [{"metric": "test"}]} # 缺少必填字段
prompt.format(**invalid_context) # 抛出异常
2.3 模板组合模式
支持通过include指令实现模板复用：
python复制base_template = RichPromptTemplate(
"""# 医疗报告分析系统
{{ header }}
{% include 'patient_info' %}
{{ content }}"""
)
patient_template = RichPromptTemplate(
"""## 患者基本信息
姓名: {{ name }}
年龄: {{ age }}
性别: {{ gender }}""",
template_id="patient_info" # 注册子模板
)
context = {
"header": "急诊科检查报告",
"name": "张三",
"age": 45,
"gender": "男",
"content": "详见各项指标分析..."
}
print(base_template.format(**context))
3. 高级应用场景
3.1 多模态提示构建
结合视觉提示模板生成图文交互指令：
python复制multimodal_prompt = RichPromptTemplate(
"""分析以下胸部X光片并描述异常：
重点关注区域：{{ focus_areas|join(", ") }}
请按以下结构回答：
1. 主要发现
2. 可能诊断
3. 建议后续检查"""
)
# 输出可直接用于多模态LLM
print(multimodal_prompt.format(
image_url="https://example.com/xray/123",
focus_areas=["右上肺叶", "心脏轮廓"]
))
3.2 动态few-shot示例
根据用户查询动态选择示例：
python复制dynamic_fewshot = RichPromptTemplate(
"""根据患者症状选择最相关的示例：
{% for example in examples %}
{{ loop.index }}. {{ example.description }}
{% endfor %}
当前症状：{{ symptoms }}
请参考上述示例进行分析："""
)
symptom_db = [
{"description": "发热+咳嗽→肺炎可能性大"},
{"description": "胸痛+呼吸困难→考虑肺栓塞"}
]
print(dynamic_fewshot.format(
examples=symptom_db[:2], # 动态截取
symptoms="持续高热伴右侧胸痛"
))
4. 性能优化实践
4.1 模板预编译
对于高频使用模板：
python复制# 首次运行编译并缓存
optimized_prompt = RichPromptTemplate(
"分析{{ topic }}的{{ aspect }}方面",
compile=True # 启用编译模式
)
# 后续调用直接使用编译结果
for i in range(1000):
optimized_prompt.format(topic="肺癌", aspect="早期症状")
4.2 批量渲染优化
使用map_reduce模式处理大批量提示：
python复制batch_prompt = RichPromptTemplate(
"""处理患者{{ patient_id }}的{{ record_type }}记录：
{{ content|truncate(500) }}"""
)
# 并行化处理
from concurrent.futures import ThreadPoolExecutor
def process_record(record):
return batch_prompt.format(**record)
with ThreadPoolExecutor() as executor:
results = list(executor.map(
process_record,
patient_records # 假设有1000条记录
))
5. 调试与问题排查
5.1 常见错误处理
| 错误类型 | 原因 | 解决方案 |
|---|---|---|
| TemplateSyntaxError | 模板语法错误 | 使用validate_template()方法预校验 |
| MissingContextVariable | 缺少必填参数 | 设置strict=False或提供默认值 |
| TypeValidationError | 参数类型不符 | 检查input_cls模型定义 |
5.2 调试技巧
- 使用
verbose=True查看模板解析过程：
python复制debug_prompt = RichPromptTemplate(
"测试{{ var1 }}和{{ var2 }}",
verbose=True
)
debug_prompt.format(var1="A") # 显示缺失变量警告
- 通过
get_used_variables()检查模板变量：
python复制print(prompt.get_used_variables()) # 输出所有模板变量
- 使用
dry_run模式测试参数传递：
python复制prompt.dry_run(var1="test") # 不执行渲染，只检查参数
6. 最佳实践建议
- 模板版本控制：将模板存储在单独文件中并用git管理
python复制with open("prompts/medical_v1.jinja2") as f:
template = RichPromptTemplate(f.read())
- 参数文档化：使用docstring记录模板要求
python复制class ClinicalPromptInput(BaseModel):
"""临床提示词输入规范
Args:
patient_id: 病历号(必须)
findings: 检查发现列表
"""
patient_id: str
findings: List[str] = []
- 性能监控：记录模板渲染耗时
python复制from time import perf_counter
start = perf_counter()
prompt.format(...)
print(f"渲染耗时: {perf_counter()-start:.2f}s")
- 安全防护：对用户输入进行转义
python复制from markupsafe import escape
user_input = "<script>alert(1)</script>"
safe_prompt = RichPromptTemplate(
"安全示例：{{ content }}",
default_filters={"content": escape}
)