实用提示：在无需独立系统的情况下构建RAG助手时我们获得的经验教训

可将此内容视为《在没有独立向量数据库的情况下构建RAG助手：我们学到的经验》中理念的面向操作员的优化版本：清晰的阶段划分、有序的代码模块，以及便于交接时参考的恢复说明。在“概览”阶段，若能将其视为可量化的基准，则效果最佳——在扩大范围之前，应先记录一份理想的处理流程、一个故障案例以及对应的回滚说明。相比庞大的脚本，更应采用小型且可测试的单元。当某一步骤出现故障时，故障原因应能明确指向某个具体的责任模块，而非整个复杂的流程。

作者心中的RAG基础

对于处于开发阶段的RAG基金会项目，应在修改代码之前明确输入内容、各步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行相应步骤，而无需猜测隐藏状态。 应将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，定义成功判定标准，并拒绝默许的半完成状态。 必须注明实际作为答案依据的段落。若没有引用，操作人员就无法区分幻觉内容与索引缺失的问题。

CREATE TABLE docs (
    id     BIGINT NOT NULL,
    path   VARCHAR(512),
    `index` INT,
    `text`  STRING,
    vector ARRAY<FLOAT>   -- 768-dim Gemini embedding
) ENGINE = OLAP
PRIMARY KEY(id)
DISTRIBUTED BY HASH(id) BUCKETS 1;

SELECT path, `index`, `text`,
       approx_cosine_similarity([0.012, -0.034, ...], vector) AS similarity
FROM docs
ORDER BY similarity DESC
LIMIT 8;

架构：从Slack事件到有依据的答案

在“基于 Slack 事件的架构”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。除了功能结果外，还需记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。必须注明支撑答案的具体内容，否则操作人员就无法区分是幻觉内容还是索引缺失导致的错误。

整体架构概览

在后续阶段中，修改代码之前需先明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测其中的隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一个位置，以便操作人员无需查看整个流程即可进行审计。 需引用实际作为答案依据的段落。若没有引用，操作人员就无法区分是虚假信息还是索引缺失导致的问题。 在后续阶段中，修改代码之前需先明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测其中的隐藏状态。 相较于庞大的脚本，应优先使用小型且可测试的单元。当某个步骤失败时，故障原因应能明确指向某个具体的责任模块，而非整个复杂的流程。

为何该技术组合适合轻量级RAG应用

在分析“为何该技术组合有效”这一阶段时，首先需明确相关约定：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改始终符合预期。 将这一阶段视为输入与验证后输出之间的契约。为相关组件命名，定义成功判定标准，杜绝无声的半完成状态。 在调整提示词之前，先使用固定的问题集来测试召回率。仅仅更换提示词往往无法改善较差的检索效果。

主键表与流式加载机制，实现文档的热插拔

在处理主键表流阶段时，首先写下相关规范：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免从演示环境过渡到共享环境时出现意外费用。 在调整提示词之前，先使用固定的问题集测试召回率。仅仅更换提示词很难改善较差的检索效果。

curl --location-trusted -u root: \
     -H "format: json" \
     -H "strip_outer_array: true" \
     -T docs_with_embedding.json \
     -XPUT http://host:8030/api/starsage/docs/_stream_load

基于工具的检索优于填充上下文

在处理“基于工具的上下文检索”阶段时，首先需明确相关规范：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放，以便操作人员无需查看整个系统结构即可进行审计。 在调整提示词之前，先使用固定的问题集来衡量召回率。仅仅更换提示词很难解决检索效果不佳的问题。 在处理“基于工具的上下文检索”阶段时，首先需明确相关规范：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 优先选择小型且可测试的单元，而非庞大的脚本。当某个步骤出现故障时，故障应能指向单一的责任模块，而非复杂的流程链。

实现可预测成本的嵌入缓存

在“可预测”阶段，将嵌入缓存视为一个可度量的对象能发挥最佳作用。在扩大范围之前，先收集一份理想的文本样本、一个故障案例以及回滚说明。 将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功标准，绝不允许出现无声的半完成状态。 将分块策略与检索策略分开。当质量指标发生变化时，修改其中一项不应强制要求重新编写另一项。

来自生产环境RAG流量的六点经验

将《生产阶段六项经验》视为可衡量的指标来运用效果最佳。在扩大范围之前，先记录一份优秀的处理结果、一个失败案例以及回滚说明。在功能结果旁同时记录处理时间以及令牌或查询成本。提前了解成本情况，就能避免在系统从演示环境过渡到共享环境时出现意外账单。应将分块策略与检索策略分开处理，当质量指标发生变化时，调整其中一个不应迫使重新编写另一个。

1. 控制幻觉现象，提示词工程比检索优化更有效

将“1个提示工程最佳实践阶段”视为可衡量的评估标准效果最佳。在扩大范围之前，先记录一份理想的操作日志、一个失败案例以及回滚说明。 将配置置于应用程序代码之外。环境文件、密钥存储和功能开关应集中存放，以便操作人员无需查看整个系统结构即可进行审计。 为每轮对话和每次会话设定Token预算。智能工具往往会过度扩展上下文，设置上限可避免演示过程变成意外的费用账单。 将“1个提示工程最佳实践阶段”视为可衡量的评估标准效果最佳。在扩大范围之前，先记录一份理想的操作日志、一个失败案例以及回滚说明。 优先选择小型且可测试的单元，而非庞大的脚本。当某个步骤失败时，故障应能指向单一责任点，而非复杂的流程链。

2. 先修复分块问题，再调整检索参数

在“2. 修改前的分块处理”阶段，应在修改代码之前明确输入内容、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，定义成功判定标准，并拒绝默许的半完成状态。 需引用实际作为答案依据的段落。没有引用的话，操作人员就无法区分幻觉内容与索引缺失的问题。

3. RAG只是工具，而非完整流程

对于属于 RAG 阶段的流程，应在修改代码之前明确输入内容、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。除了功能结果外，还需记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在流程从演示环境转向共享环境时出现意外费用。必须注明实际用于生成答案的文本片段；没有引用的话，操作人员就无法区分是幻觉内容还是索引缺失导致的错误。

4. 遵循平台的会话模型

在“遵循平台”阶段的第4步中，应在修改代码之前明确输入参数、该步骤的负责人以及终止条件。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测其中的隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，以便操作人员无需查看整个流程即可进行审计。 当下一步是代码执行或工具调用时，宜使用具有结构化格式且经过模式验证的输出，而非自由形式的文本。 在“遵循平台”阶段的第4步中，应在修改代码之前明确输入参数、该步骤的负责人以及终止条件。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测其中的隐藏状态。 相比庞大的脚本，更应采用小型且可测试的单元。当某个步骤失败时，故障原因应能明确指向某个特定功能模块，而非整个复杂的流程。

contents = []
for turn in history[-MAX_CONTEXT_MESSAGES:]:
    contents.append({"role": turn["role"], "parts": [{"text": turn["text"]}]})
contents.append({"role": "user", "parts": [{"text": query}]})

5. 尽早设计工具，而非在发布后才处理

在进入“尽早设计工具”阶段时，首先列出相关契约：所需的输入参数、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改始终符合初始要求。 将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功标准，杜绝默许的部分完成情况。 在调整提示词之前，先使用固定的问题集来测试召回率。仅仅更换提示词往往无法改善较差的检索效果。

6. 大力使用缓存，严格监控每一分支出

在处理“积极跟踪缓存”这一阶段时，首先需明确相关约定：所需的输入参数、成功标志，以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。 在调整提示词之前，先使用固定的问题集测试召回率。仅仅更换提示词往往无法改善较差的检索效果。

诚实的权衡

在“诚实权衡”阶段工作时，首先需写明契约内容：所需输入、成功标志以及部分失败时的处理方式。这份清单能确保后续的代码修改保持透明。 应将配置信息与应用程序代码分开存放。环境文件、密钥存储以及功能开关应集中于一处，以便操作人员无需查看整个系统结构即可进行审计。 在调整提示词之前，先使用固定的问题集来衡量召回率。仅仅更换提示词往往无法解决检索效果不佳的问题。 在“诚实权衡”阶段工作时，首先需写明契约内容：所需输入、成功标志以及部分失败时的处理方式。这份清单能确保后续的代码修改保持透明。 相比庞大的脚本，更应选择小型且可测试的单元。当某个步骤出现故障时，故障点应指向单一职责，而非复杂的流程链。

Rocky展示了什么

将“Rocky Demonstrates”阶段视为可度量的工作面最为有效。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。把这一阶段视为输入与已验证输出之间的契约，为相关成果命名，明确成功标准，绝不允许出现悄无声息的半完成状态。应将分块策略与检索策略分开，当质量指标发生变化时，修改其中一项不应强制要求重写另一项。

操作检查清单

在处理操作检查清单阶段时，首先要写下契约内容：所需输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持透明可溯。

需同时记录正常流程与故障恢复流程。重试机制、人工审核环节以及错误处理方式都是产品本身的组成部分，而非后续的完善工作。

在调整提示词之前，先在固定的问题集上测试召回率。频繁更换提示词很难改善较差的检索效果。

锁定依赖版本，并记录用于演示的图像摘要。可重复性比经验知识更重要。

优先选择小型、易于测试的单元，而非庞大的脚本。当某个步骤出错时，错误应指向单一责任点，而非复杂的流程链。

在调整提示词之前，先在固定的问题集上测试召回率。频繁更换提示词很难改善较差的检索效果。

在推广整个技术栈之前，先冻结版本，为关键路径保存标准记录，并确认回滚步骤。共享环境需要设置速率限制、租户检查机制，以及明确的密钥轮换负责人。与其追求花哨的一次性演示，不如注重扎实的可靠性。

关于26df51f33219的批处理说明：不要将提供者密钥放入仓库中，设定每会话的令牌上限，并将转录内容存储在评估测试用例旁边，以便后续更换模型时仍能保持可比性。