实用提示：Spring AI 实战指南——利用元数据筛选RAG结果
《实用笔记》操作指南：Spring AI 实战方案——利用元数据筛选 RAG 结果：为采用该模式的团队提供的契约、检查项及可直接插入的代码片段。
本指南将逐步构建从原始材料到可运行系统的完整流程，适用于“Spring AI Recipe：利用元数据过滤RAG结果”这一主题。重点在于可操作的步骤、明确的检查点，以及可直接放入代码库的代码，无需猜测其用途。 在概览阶段，应在修改代码之前明确输入参数、各步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测其中的隐藏状态。 除了功能结果外，还需记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在流程从演示环境转向共享环境时出现意外费用。
On each player's turn, they place a dog, food bowl, or toy into
one of the three play yards. The game ends when a player has
placed their last dog into a yard. Then each player who hasn't
played in that round gets to place one more item into a yard
until the last player so that all players have an equal number
of turns.
On their turn, a player starts by moving any flies on the board
to the same space as an adjacent frog (effectively the frog has
eaten that fly). Then the player can either place 1 fly adjacent
to a frog on the board as a distraction so that the frog won't
jump or they may place a frog of their player color onto any
empty space. If the frog is adjacent to another frog (even if it
is their own), the adjacent frog will jump two spaces in any
direction away from the frog that was just placed. The direction
of the jump is decided by the current player. If the frog jumps
off the board, then that frog is out of play.
The game ends when all players have placed all of their frogs
(not counting frogs that have jumped off the board). The player
with the most frogs remaining on the board wins.
When it is a player's turn, they will draw a card from the
ingredients deck and add it to their hand. Then they may play
any ingredient card from their hand to add that ingredient to
one of up to three tacos in progress. Or, if they have a crunch
card in their hand, then they may play it to remove one
ingredient from any one opponent's taco. The first player to
completely build 3 tacos wins.
@Configuration
public class RagIngestionConfig {
private static final Logger logger =
LoggerFactory.getLogger(RagIngestionConfig.class);
@Value("${rag.documents}")
Resource[] documentResources;
@Bean
@Order(-1)
ApplicationRunner load(VectorStore vectorStore) {
return args -> {
for (Resource documentResource : documentResources) {
var filename = documentResource.getFilename();
logger.info("Loading document from {}.", filename);
var reader = new TikaDocumentReader(documentResource);
var splitter = TokenTextSplitter.builder().build();
vectorStore.accept(
splitter.apply(
reader.get()));
}
logger.info("Document loading complete.");
};
}
}
How can I help?
> What can I do on my turn?
- Draw a card from the ingredients deck and add it to your hand.
- Then you may either:
- Play any ingredient card from your hand to add that ingredient
to one of up to three tacos in progress, or
- Play a crunch card (if you have one) to remove one ingredient
from any one opponent's taco.
- On your turn you place a dog, a food bowl, or a toy into one of
the three play yards.
- The game ends when a player has placed their last dog; then players
who haven't yet played in that round get one more placement so all
players have equal turns.
为文档添加元数据
在处理“为阶段添加元数据”这一任务时，首先需列出相关规范：所需输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合要求。 应将配置信息与应用程序代码分开。环境文件、密钥存储以及功能开关应集中存放于一个位置，这样操作人员无需查看整个系统结构即可进行审计。 在调整提示词之前，需先用固定的问题集来测试召回率。仅仅更换提示词往往无法解决检索效果不佳的问题。
@Bean
@Order(-1)
ApplicationRunner load(VectorStore vectorStore) {
return args -> {
for (Resource documentResource : documentResources) {
var filename = documentResource.getFilename();
logger.info("Loading document from {}.", filename);
var reader = new TikaDocumentReader(documentResource);
var splitter = TokenTextSplitter.builder().build();
var titleTag =
filename.substring(0, filename.lastIndexOf('.'));
vectorStore.accept(
splitter.apply(
reader.get().stream()
.peek(document ->
document.getMetadata()
.put("title", titleTag))
.toList()));
}
logger.info("Document loading complete.");
};
}
title = camp-bowwow
确定用户询问的是哪款游戏
在规划“确定使用哪个游戏阶段”时，首先需列出相关规范：所需输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及错误消息处理都是产品本身的组成部分，而非后续的优化工作。 在调整提示词之前，需先使用固定的问题集来衡量检索效果。仅仅更换提示词往往无法解决检索能力不足的问题。
@Service
public class TitleHelper {
private final ChatClient chatClient;
public TitleHelper(ChatModel chatModel) {
this.chatClient = ChatClient.builder(chatModel).build();
}
public String determineGameTitle(String question) {
var title = chatClient.prompt()
.user(userSpec -> userSpec
.text("""
Your job is to try to determine the title of a game from
the question asked.
The game choices are:
- camp-bowwow
- frog-panic
- taco-truck
- unknown
If the game's title isn't explicitly mentioned in the
question, or you don't recognize the game's title, then
say "unknown".
The question is:
{question}
""")
.param("question", question))
.call()
.content();
return title.equals("unknown") ? null : title;
}
}
向量搜索的过滤
在处理向量搜索过滤阶段时，首先需明确相关规范：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 优先选择小型、可测试的单元，而非庞大的脚本。当某个步骤出现故障时，故障应指向单一责任点，而非复杂的流程链。 在调整提示词之前，先使用固定的问题集来衡量召回率。仅仅更换提示词很难改善较差的检索效果。 在处理向量搜索过滤阶段时，首先需明确相关规范：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 在功能结果之外，还需记录执行时间以及token或查询成本。提前了解成本情况，可避免从演示环境过渡到共享环境时出现意外费用。
@Bean
ApplicationRunner go(
ChatClient chatClient,
TitleHelper titleHelper) {
return args -> {
System.out.println("How can I help?\n");
try (Scanner scanner = new Scanner(System.in)) {
while (true) {
System.out.print("> ");
if (!scanner.hasNextLine()) break;
var input = scanner.nextLine();
if (input.isBlank()) continue;
var requestSpec = chatClient.prompt(input);
var gameTitle =
titleHelper.determineGameTitle(input);
var answer = requestSpec
.advisors(spec -> {
spec.param(
ChatMemory.CONVERSATION_ID,
"DEMO");
if (gameTitle != null) {
spec.param(
QuestionAnswerAdvisor.FILTER_EXPRESSION,
String.format(
"title == '%s'",
gameTitle));
}
})
.call()
.content();
System.out.println("\n - " + answer);
}
}
};
}
title == 'camp-bowwow'
试用阶段
将“试用阶段”视为可度量的测试环境最为有效。在扩大范围之前，需记录一个成功的案例、一个失败案例以及回滚说明。 配置应与应用程序代码分开存放。环境文件、密钥存储和功能开关应集中管理，以便操作人员无需查看全部内容即可进行审计。 分块策略与检索策略应相互独立。当质量指标发生变化时，修改其中一项不应强制要求重新编写另一项。
How can I help?
> I'm playing Camp Bowwow. What do I do when it's my turn?
- On your turn you place one item - either a dog, a food bowl,
or a toy - into one of the three play yards.
(For reference: the game ends when a player has placed their last
dog; then any players who haven't yet played in that round each get
one more item turn in order until the last player, so all players
have equal turns.)
> I'm playing Frog Panic. What do I do when it's my turn?
- On your turn:
1. First, move any flies on the board onto the same space as an
adjacent frog (the frog eats that fly).
2. Then choose one action:
- Place 1 fly adjacent to a frog on the board as a distraction
(so that frog won't jump), or
- Place a frog of your color onto any empty space.
If the frog you place is adjacent to another frog (even your own),
that adjacent frog jumps two spaces away in any direction you choose.
If a frog jumps off the board it is out of play.
(For reference: the game ends when all players have placed all their
frogs; the player with the most frogs remaining on the board wins.)
超越简单相似性
“超越相似性”阶段若被视为可度量的指标，效果会更好。在扩大范围之前，需记录一份理想处理结果、一个故障案例以及回滚说明。
操作检查清单
“操作检查清单”阶段若被视为可度量的指标，效果会更好。在扩大范围之前，需记录一份理想处理结果、一个故障案例以及回滚说明。
应将此阶段视为输入与经过验证的输出之间的契约。为相关文档命名，明确成功标准，杜绝默许的半完成状态。
将分块策略与检索策略分开。当质量指标发生变化时，修改其中一项不应强制重新编写另一项。
在预算允许的情况下，使用测试数据而非真实的付费 API，在持续集成过程中添加用于检测关键路径的冒烟测试。
在功能结果旁记录处理时间以及令牌或查询成本。提前了解成本情况，可避免在系统从演示环境切换到共享环境时出现意外账单。
将分块策略与检索策略分开。当质量指标发生变化时，修改其中一项不应强制重新编写另一项。
在推广该技术栈之前，先冻结版本，为关键路径生成标准参考记录，并确认回滚步骤。共享环境需要设置速率限制、进行租户验证，同时明确密钥轮换的责任人。与其追求华丽的临时演示，不如注重扎实的可靠性。
关于bef2f8a7cb72的批量处理说明：不要将提供者密钥放入代码仓库，设定单次会话的令牌上限，并将转录内容存储在评估测试用例旁边，以便后续更换模型时仍能保持可比性。
针对强化安全措施的第0阶段，在修改代码之前需明确输入内容、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。需同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及错误处理都属于产品功能的一部分，而非后续需要完善的内容。
强化安全措施细节0/963：需统计该步骤的运行时间、错误类型以及令牌消耗情况，然后依据固定的评估标准而非主观判断来决定是否保留该更改。
在处理强化措施的第一阶段时，首先写下相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合约定。 将这一阶段视为输入与验证后输出之间的契约。为相关产物命名，明确成功判定标准，杜绝默许部分完成的情况。
强化措施细节 1/963：需测量该步骤的耗时、错误类型以及令牌消耗情况，然后依据固定的评估标准而非主观感受来决定是否保留该变更。