提示词使用指南

什么是提示词模板

提示词模板是用于优化与大模型交互的提示或查询操作的模板化配置。通过模板化管理，可以实现提示词的复用、版本控制和集中维护，确保 AI 响应的准确性和一致性。

核心价值

标准化交互：统一管理系统中所有 AI 交互的提示词，确保输出质量
版本控制：完整的历史版本记录，支持版本对比和回滚
变量支持：通过模板变量实现动态内容注入，StringTemplate 使用 {variableName}，FreeMarker 使用 ${variableName}
分类管理：按功能分类（RAG、SQL、OCR、MCP、GEN 等）组织提示词
降级机制：数据库不存在时自动回退到 resources/prompts/ 目录文件

在代码中使用提示词

后台代码通过 PromptCodeConstants 常量接口引用提示词模板编码，再通过 PromptBuilder 工具类渲染最终内容。

基本使用流程

// 1. 引用常量
String code = PromptCodeConstants.KNOWLEDGE_RAG_QA;

// 2. 使用默认参数渲染（自动注入系统时间）
String prompt = PromptBuilder.render(code);

// 3. 使用自定义参数渲染
Map<String, Object> params = new HashMap<>();
params.put("userName", "张三");
params.put("question", "如何使用提示词？");
String prompt = PromptBuilder.render(code, params);

// 4. 直接渲染字符串模板
String prompt = PromptBuilder.renderString("你好 {userName}", Map.of("userName", "张三"));

渲染优先级

PromptBuilder.render() 优先从数据库加载模板（带 Redis 缓存），若数据库不存在，则自动回退到 resources/prompts/ 目录下同名文件，实现平滑迁移。

提示词常量定义

系统在 PromptCodeConstants.java 中预定义了所有提示词常量，常量值保留文件扩展名（.st/.ftl）以兼容文件回退机制：

public interface PromptCodeConstants {
  // RAG 知识检索相关
  String KNOWLEDGE_RAG_QA        = "knowledge-rag-qa.st";
  String KNOWLEDGE_RAG_SUMMARY   = "knowledge-rag-summary.st";
  String KNOWLEDGE_RAG_COMPRESS  = "knowledge-rag-compress.st";
  String KNOWLEDGE_SYSTEM        = "knowledge-system.st";

  // SQL 数据库查询相关
  String CHAT2SQL_FUNCTION_CALLING = "Chat2SqlFunctionCalling.st";
  String CHAT2DB_RESULT_CHART      = "chat2db-result-chart.st";
  String CHAT2DB_TABLE_SCHEMA      = "chat2db-table-schema.ftl";

  // OCR 图像识别相关
  String OCR_IMAGE      = "ocr-image.st";
  String OCR_IMAGE_JSON = "ocr-image-json.st";

  // MCP 模型上下文协议
  String MCP = "mcp.st";

  // GEN 内容生成
  String GEN_TEXT     = "gen-text.st";
  String GEN_MARKMAP  = "gen-markmap.st";
  String AI_POSTER    = "ai-poster.ftl";

  // 其他
  String META_PROMPT  = "meta-prompt.st";
  String WEB_SEARCH   = "web-search.st";
}

扩展提示词常量

如需添加新的提示词模板：

在管理界面创建模板，填写唯一的编码（如 my-feature.st）
在 PromptCodeConstants.java 中添加对应的常量
在代码中通过 PromptBuilder.render(PromptCodeConstants.MY_FEATURE, params) 调用

模板变量说明

提示词模板支持动态变量注入，系统会自动注入 systemTime（当前时间）作为默认变量：

StringTemplate 使用 {variableName} 格式（Spring AI PromptTemplate）
FreeMarker 使用 ${variableName} 格式，支持条件判断和循环

StringTemplate 模板示例（.st 后缀）：

你是一个专业的知识库助手。

当前时间：{systemTime}
用户名称：{userName}

请基于以下知识库内容回答用户问题：
{knowledgeContent}

用户问题：{question}

FreeMarker 模板示例（.ftl 后缀）：

角色：AI 助手
用户：${userName}
时间：${currentTime?string("yyyy-MM-dd HH:mm:ss")}
<#if historyMessages?has_content>
历史对话：
<#list historyMessages as msg>
- ${msg.role}: ${msg.content}
</#list>
</#if>
当前问题：${userQuestion}

在应用中使用提示词

聊天对话中使用

在自由模式下点击快捷按钮，直接拉起提示词选择界面：

选择合适的提示词后，系统会自动填充到对话输入框中，支持快速应用预设的提示词模板。

提示词模板管理

模板列表

系统提供完整的提示词模板管理界面，支持按编码、名称、分类、状态进行查询：

主要字段说明：

编码：模板的唯一标识，如 knowledge-rag-qa.st，与 PromptCodeConstants 中的常量对应
名称：模板的显示名称，如"知识库 RAG 问答"
分类：模板所属功能分类（RAG / SQL / OCR / MCP / GEN / 其他）
模板类型：支持 StringTemplate（.st）或 FreeMarker（.ftl）两种模板引擎
版本：当前版本号，每次修改自动递增
状态：启用 / 禁用，禁用后调用时会抛出异常
系统内置：标记为系统内置的模板不允许删除

创建和编辑模板

点击"新增"或"编辑"按钮打开模板编辑对话框。

基本信息配置：

编码：创建后不可修改，建议使用有意义的命名，如 knowledge-rag-qa.st
名称：简短描述模板用途
分类：选择模板功能分类，便于管理和查询
模板类型：选择 StringTemplate 或 FreeMarker
描述说明：详细说明模板的用途和使用场景
变更说明：编辑时必填，记录本次修改的内容，系统自动保存旧版本到历史记录

编码规则

模板编码创建后不可修改，且必须与 PromptCodeConstants.java 中定义的常量保持一致。系统根据编码从数据库加载模板内容，如需在代码中使用，请先在常量接口中添加对应常量。

模板引擎对比

系统支持两种模板引擎，适用于不同的使用场景：

StringTemplate 是基于 Spring AI PromptTemplate 的轻量级模板引擎，语法简洁，适合简单的变量替换场景。适合以下场景：

提示词结构固定，仅需替换变量
不需要根据条件动态调整内容
追求更简洁的模板语法

模板分类说明

系统预定义了以下提示词模板分类，每个分类对应不同的 AI 功能场景：

分类	说明	典型模板示例
RAG	知识库检索增强生成	知识库问答、摘要生成、结果压缩
SQL	数据库查询相关	Chat2SQL 生成、结果处理、图表生成
OCR	图像识别和文字提取	图像识别、安全检测、格式化输出
MCP	模型上下文协议	MCP 服务交互
GEN	内容生成	海报、文案、思维导图、信息图
其他	通用功能	元提示词、推理系统、网页搜索

模板预览和测试

点击"预览"按钮测试模板渲染效果：

左侧输入参数：以 JSON 格式输入模板变量的值

{
  "systemTime": "2025-12-13 15:30:00",
  "userName": "张三",
  "question": "如何使用 AI 提示词？"
}

点击开始渲染：系统使用输入的参数渲染模板，并在右侧显示渲染结果

语法校验

保存和编辑模板时，系统会自动对 StringTemplate 和 FreeMarker 语法进行校验，语法错误时会给出具体的错误提示。

提示词智能优化

系统内置 AI 驱动的提示词优化功能，帮助快速提升提示词质量。

优化流程

在模板列表中点击"优化"按钮
左侧显示原始模板内容（支持编辑）
选择优化模板和调整参数
点击"优化模板"按钮
右侧显示优化后的内容
确认无误后点击"保存"

优化模板类型

系统提供三种优化策略：

默认模板：

深度理解用户意图，补充关键上下文
明确任务目标和期望输出格式
保持原始意图，语言精练

简洁模板：

压缩为 1-2 句高密度指令
删除非必要描述，直击核心
适合简单任务场景

扩展模板：

结构化重构，包含核心目标、角色背景、执行步骤
详细定义输出要求和约束条件
适合复杂任务场景

优化参数：

使用模型：选择用于优化的 AI 模型
温度：控制输出的随机性（0-1）
- 低值（0-0.3）：输出更稳定、保守
- 中值（0.4-0.7）：平衡创新性和稳定性
- 高值（0.8-1.0）：输出更有创意、多样

变量保护

优化功能会自动保护模板变量（StringTemplate 的 {variableName} 和 FreeMarker 的 ${variableName} 格式），确保变量在优化后的内容中完整保留，不会被修改或删除。

版本控制

查看历史版本

点击"历史"按钮查看模板的所有历史版本。

历史记录包含：

版本号（自动递增）
变更类型（新建 / 更新 / 回滚）
变更说明（创建或编辑时填写）
变更人和变更时间

版本对比

在历史版本列表中点击"版本对比"按钮，对比两个版本的差异：

左侧选择旧版本
右侧选择新版本（默认为当前版本）
使用红色 / 绿色高亮显示删除 / 新增的内容
支持并排对比和行内对比两种模式

版本回滚

如果发现当前版本存在问题，可以回滚到历史版本：

在历史版本列表中选择目标版本
点击"回滚"按钮
填写回滚说明
确认后系统会创建新版本（变更类型为"回滚"），内容恢复为目标版本

回滚机制

版本回滚不是删除当前版本，而是基于目标版本内容创建一个新版本，历史记录完整保留，支持再次回滚。

缓存管理

提示词模板在 Service 层使用 Redis 缓存（缓存键：prompt:template），避免频繁查询数据库。

修改模板后若需立即生效，可在管理界面点击"刷新缓存"按钮，清空所有提示词模板缓存。

#提示词使用指南

#什么是提示词模板

#在代码中使用提示词

#基本使用流程

#提示词常量定义

#模板变量说明

#在应用中使用提示词

#聊天对话中使用

#提示词模板管理

#模板列表

#创建和编辑模板

#模板引擎对比

#模板分类说明

#模板预览和测试

#提示词智能优化

#优化流程

#优化模板类型

#版本控制

#查看历史版本

#版本对比

#版本回滚

#缓存管理