Dify实战：用Excel驱动大模型，实现数据库调优的自动化验证

1. 从手动测试的“地狱”到自动化验证的“天堂”

每次数据库调优之后，你是不是也和我一样，感觉最头疼的不是写SQL，而是后续那无穷无尽的回归测试？我经历过太多次了：改了一个索引，优化了一个查询，然后就得吭哧吭哧地打开测试文档，把几十甚至上百个预设的查询问题，一个一个手动执行，再拿返回结果去和标准答案比对。这个过程不仅枯燥，而且极其容易出错，眼睛一花就可能看漏一个数据，更别提每次调优都要重复一遍，时间成本高得吓人。

这个痛点，我相信很多后端开发和DBA都深有体会。我们花在验证优化效果上的时间，有时候甚至超过了优化本身。更麻烦的是，随着业务发展，测试用例集（我们通常用Excel维护）会越来越庞大，手动验证的可行性几乎为零。这时候，一个自动化的、智能的验证流水线就成了刚需。

我一开始也想过用更专业的A/B测试或LLM评估平台，比如Langfuse，但说实话，那些工具学习曲线陡峭，配置复杂，对于快速解决眼前问题来说，有点“杀鸡用牛刀”的感觉。我的原则是：先用最简单直接的方式把问题跑通，解决掉80%的重复劳动，再去追求那20%的精益求精。 所以，我把目光投向了 Dify 这个低代码的AI应用开发平台。它上手快，能快速连接大模型，处理结构化数据，简直是打造这种“智能批改”系统的绝佳画布。

我的目标很明确：构建一个“上传Excel -> 大模型批量批改 -> 输出结构化报告”的自动化流水线。 你只需要把维护好的测试用例Excel表格（包含问题ID、SQL查询语句、期望结果）丢进去，剩下的就交给工作流。它会自动调用大模型（比如GPT-4、DeepSeek等）来执行查询、判断对错，最后生成一份清晰的测试报告，告诉你哪些用例通过了，哪些失败了，失败的原因可能是什么。这样一来，每次调优后的验证工作，从几小时压缩到了几分钟，而且结果准确可靠。

下面，我就把自己从零搭建这个系统的完整过程、踩过的坑以及最终的解决方案，毫无保留地分享给你。即使你之前没怎么用过Dify，跟着我的步骤走，也能快速复现出一个属于你自己的数据库调优自动化验证工具。

2. 核心思路与Dify工作流设计蓝图

在动手写代码和配置之前，我们得先把整个自动化流水线的逻辑想清楚。这就像盖房子要先画图纸一样，清晰的蓝图能避免后面走很多弯路。

整个系统的核心输入是一张Excel表格，通常包含三列：

• _id: 测试用例的唯一标识，比如 TC001。
• question: 需要测试的数据库查询语句，例如 SELECT COUNT(*) FROM users WHERE status = 'active';。
• answer: 该查询语句在当前数据库状态下应该返回的正确结果。注意，这里的结果可能是一个数字、一个字符串，甚至是一个小的结果集。

我们的目标是：让大模型扮演一个“严格的判官”。工作流需要依次执行以下步骤：

1. 解析Excel：将用户上传的Excel文件内容，转换成程序能处理的标准化数据结构（比如列表或字典）。
2. 迭代处理：因为Excel里有多行数据，我们需要对每一行（即每一个测试用例）执行相同的“提问-判断”流程。
3. 提问与执行：将 question（SQL语句）发送给大模型，并要求大模型连接到你指定的数据库去执行它，获取实际结果。这里的关键是，我们需要在提示词（Prompt）中清晰地告诉大模型数据库的连接信息（当然，是以安全的方式，比如通过环境变量或Dify的密钥管理）和执行的上下文。
4. 智能批改：大模型拿到实际执行结果后，将其与 answer（期望结果）进行比对。这里的比对不是简单的字符串相等，因为结果可能包含浮点数精度问题、结果集顺序问题等。我们需要引导大模型进行“智能”比对，比如判断数值是否在误差范围内，或者判断两个结果集在语义上是否等价。
5. 结果收集：将每一个用例的批改结果（通过/失败、实际结果、差异说明）收集起来。
6. 报告生成：将所有用例的结果汇总，生成一份格式清晰、易于阅读的报告（可以是Markdown、HTML或另一个Excel文件），并返回给用户。

在Dify中，我们可以用“工作流”来可视化地搭建这个流水线。你会用到几个关键组件：

• “知识库”或“上传文件”节点：用于接收用户上传的Excel文件。
• “代码”节点：这是我们的“瑞士军刀”，用来编写Python脚本解析Excel数据，处理Dify平台的一些限制（后面会详细说）。
• “迭代循环”节点：用于对解析后的测试用例列表进行循环，逐个处理。
• “LLM”节点：配置你选择的大模型（如GPT-4），并编写精心设计的提示词，让它去执行SQL和比对结果。
• “文本处理”与“合并”节点：用于整理和汇总最终的批改报告。

整个工作流的骨架大致如下图所示（请想象一个流程图）：文件上传 -> 解析为数组 -> 进入迭代循环 -> (循环内：提取单条用例 -> LLM执行与判断 -> 输出单条结果) -> 合并所有结果 -> 生成最终报告。

3. 实战第一步：用Python代码破解Excel解析与数组传递难题

好了，蓝图有了，我们开始动手。第一个拦路虎就是：如何把用户上传的Excel文件，变成Dify工作流里能一条条处理的数据？

Dify的“上传文件”节点很方便，但它输出的内容通常是一个文本块，或者一个文件路径。而我们的“迭代循环”节点，理想情况下是希望接收一个列表（List），这样它才能自动地遍历列表中的每一个元素。但Dify的界面操作有时无法直接生成这种复杂数据结构。

这就是需要“代码”节点大显身手的地方。我们可以用Python写一个小脚本，充当数据格式的“转换器”。我直接把我调试好的代码贴出来，并逐行给你解释。

首先，我们在Dify工作流中拖入一个“代码”节点，选择Python语言。这个节点的任务是：接收上传的Excel内容（可能是文本格式），将其解析并重组为我们需要的三个数组：id_list, question_list, answer_list。

def main(arg1: str) -> dict:
    """
    将上传的Excel表格文本内容，解析为三个独立的数组。
    输入arg1: 通常是包含表格标记（如Markdown表格）的字符串。
    输出: 一个字典，包含 '_id', 'question', 'answer' 三个键，对应的值都是列表。
    """
    # 初始化结果字典
    result = {
        "_id": [],   # 用于存放用例ID的列表
        "question": [], # 用于存放SQL问题的列表
        "answer": []    # 用于存放期望答案的列表
    }

    # 预处理输入：如果arg1是列表（Dify有时会传列表），先合并成字符串
    input_str = '\n'.join(arg1) if isinstance(arg1, list) else arg1

    # 按行分割输入内容
    for line in input_str.split('\n'):
        line = line.strip()
        # 跳过空行和可能的表格分隔行（如 |---|---|）
        if not line or line.startswith('|---'):
            continue

        # 假设每行数据是用竖线'|'分隔的（类似Markdown表格）
        # 例如：| TC001 | SELECT * FROM users | 100 |
        cols = [c.strip() for c in line.split('|') if c.strip()]

        # 确保我们正好拿到三列数据
        if len(cols) != 3:
            continue  # 如果不是三列，跳过这行（可能是表头或其他格式不对的行）

        try:
            # 将三列数据分别存入对应的列表
            # 第一列是ID，强制转为字符串，避免后续类型错误
            result["_id"].append(str(cols[0]))
            # 第二列是SQL语句，也转为字符串
            result["question"].append(str(cols[1]))
            # 第三列是答案，我们保持其原始字符串形式，后续由LLM判断类型
            result["answer"].append(str(cols[2]))
        except ValueError as e:
            # 如果转换出现意外错误，记录并跳过该行（生产环境可考虑记录日志）
            print(f"解析行时出错 '{line}': {e}")
            continue

    # 返回解析好的字典
    return result

这段代码的核心逻辑很简单：它像一个小型的解析器，把文本形式的表格数据“拆解”开。你可能会问，为什么不用 pandas 库？在Dify的代码节点环境里，不一定预装了所有第三方库，用纯Python字符串操作是最稳妥、依赖最少的方式。而且，用户上传的Excel在Dify中常常被转换成Markdown表格文本，用竖线分割，这个解析方法正合适。

运行这个节点后，它会输出一个包含三个列表的字典。接下来，我们就可以把 result["_id"], result["question"], result["answer"] 这三个列表，作为变量连接到后续的节点了。

4. 攻克Dify迭代模块的“单变量”限制

当我们兴冲冲地把上面生成的三个列表，拖到“迭代循环”节点上时，第二个坑出现了：Dify的迭代循环节点，默认每次只允许接收一个变量进行迭代！

这是什么意思？假设我们有三个列表：ids = [‘TC001’， ‘TC002’], questions = [‘select…’， ‘select…’], answers = [‘100’， ‘200’]。我们希望的迭代是：第一次循环处理 (‘TC001’， ‘select…’， ‘100’)，第二次处理 (‘TC001’， ‘select…’， ‘100’)。但迭代节点如果只接 ids 列表，那在循环内部，我们就拿不到当前循环对应的 question 和 answer 了。

这确实是个限制，但别慌，有完美的解决方案。我们不能让迭代节点同时迭代三个列表，但我们可以在迭代循环的内部，通过索引去“主动查找”另外两个列表里对应的值。

具体怎么做呢？我们调整一下思路：

1. 我们让迭代节点只迭代其中一个列表，比如 _id 列表。这样，在每次循环里，我们能得到一个当前循环的索引（index）和当前循环的ID值。
2. 然后，我们在迭代循环内部，再放置一个“代码”节点。这个节点的任务就是：根据传入的当前索引（index），去另外两个全局的列表（question_list， answer_list）里，把对应位置的值“捞”出来。

这样，我们就实现了“用一个索引，牵出三个值”的效果。下面是循环内部那个“代码”节点的实现：

def main(index, question_list, answer_list):
    """
    根据索引，从全局的问题和答案列表中取出当前迭代对应的值。
    输入:
        index: 当前迭代的索引（整数）。
        question_list: 所有SQL问题的列表。
        answer_list: 所有期望答案的列表。
    输出: 一个包含当前索引、问题和答案的字典。
    """
    # 1. 类型安全检查：确保索引是数字
    try:
        idx = int(index)
    except (ValueError, TypeError):
        raise ValueError(f"索引必须为可转换的数字，当前值: {repr(index)}")

    # 2. 类型安全检查：确保输入的两个列表确实是列表类型
    if not isinstance(question_list, list):
        raise TypeError(f"question_list 必须是列表类型，当前类型: {type(question_list).__name__}")
    if not isinstance(answer_list, list):
        raise TypeError(f"answer_list 必须是列表类型，当前类型: {type(answer_list).__name__}")

    # 3. 防御性编程：检查列表是否为空
    error_msgs = []
    if len(question_list) == 0:
        error_msgs.append("question_list 数组为空，无法获取问题。")
    if len(answer_list) == 0:
        error_msgs.append("answer_list 数组为空，无法获取答案。")
    if error_msgs:
        raise ValueError(" | ".join(error_msgs))

    # 4. 计算有效长度（以两个列表中最短的那个为准，防止索引越界）
    valid_length = min(len(question_list), len(answer_list))

    # 5. 检查索引是否在有效范围内
    if idx < 0 or idx >= valid_length:
        raise IndexError(f"索引 {idx} 越界！有效索引范围是 0 到 {valid_length-1}。")

    # 6. 返回当前迭代所需的数据包
    return {
        'current_index': idx,
        'current_question': question_list[idx],
        'current_answer': answer_list[idx]
    }

这个函数我加了非常详细的错误检查，这是在实际项目中踩坑换来的经验。因为Dify工作流中变量传递有时类型会有些意外，比如索引可能以字符串形式传来。这些检查能让你在调试时快速定位问题，而不是得到一个模糊的“执行失败”提示。

现在，工作流就清晰了：第一个代码节点解析Excel，输出三个列表。迭代节点遍历 _id 列表。在迭代循环内部，第二个代码节点接收 当前索引、全局的question_list和全局的answer_list，输出一个包含 current_question 和 current_answer 的数据包。这个数据包，就可以完美地喂给后面的LLM节点进行批改了。

5. 设计大模型提示词：让它成为靠谱的“数据库判官”

数据流转的问题解决了，接下来是最核心的一环：如何让大模型准确地执行SQL并判断对错？ 这完全取决于我们给它的“指令”是否清晰、无歧义。一个糟糕的提示词，会让大模型胡言乱语；一个好的提示词，则能让它像一位经验丰富的DBA一样工作。

我们的LLM节点（比如配置为GPT-4）需要完成两个任务：

1. 执行SQL：连接到你指定的数据库，运行 current_question 中的查询语句。
2. 比对结果：将执行得到的实际结果，与 current_answer 中的期望结果进行比对，并给出判断。

下面是我经过多次调试后，一个比较稳定可靠的提示词模板。你需要根据你的数据库类型（MySQL、PostgreSQL等）和连接方式稍作修改。

你是一个专业的数据库查询验证助手。请严格按照以下步骤执行：

**步骤1：连接并执行查询**
- 数据库类型：[你的数据库类型，如MySQL]
- 连接信息（已通过环境变量`DB_CONNECTION_STRING`提供，请直接使用）。
- 请执行以下SQL查询语句：

{{current_question}}

- 执行后，请将查询返回的**实际结果**完整地提取出来。如果结果是多行多列，请以清晰的表格形式呈现；如果是一个标量值（单个数字或字符串），请直接给出。

**步骤2：结果比对与判断**
- 期望的正确结果是：`{{current_answer}}`
- 请将**实际结果**与**期望结果**进行比对。比对时请注意：
    1.  对于数值结果，允许微小的浮点数精度误差（例如，0.0001以内的差异视为相等）。
    2.  对于字符串结果，需完全匹配（大小写敏感，除非特别说明）。
    3.  对于结果集，比较其**数据内容**是否一致，而不要求严格的顺序一致（你可以先对行进行排序再比较）。
- 根据比对结果，给出明确的判断：
    - 如果一致，输出：`[PASS]`
    - 如果不一致，输出：`[FAIL]`

**步骤3：输出结构化信息**
请将你的最终输出严格遵循以下JSON格式，不要有任何额外的解释或Markdown标记：

```json
{
  "test_id": "{{当前循环的ID，可以从上下文获取}}",
  "sql_query": "{{current_question}}",
  "expected_result": "{{current_answer}}",
  "actual_result": "【这里填写你执行查询后得到的实际结果】",
  "judgment": "[PASS] 或 [FAIL]",
  "reason": "如果通过，可写‘结果一致’；如果失败，请简要说明不一致之处（例如：‘实际结果为105，期望为100’）。"
}

重要提醒：只输出上面的JSON对象，不要输出其他任何内容。

这个提示词有几个关键点：
- **角色设定**：明确告诉模型它要扮演什么角色。
- **步骤清晰**：把复杂任务拆解成1、2、3步，模型更容易遵循。
- **比对规则具体化**：明确说明了数值、字符串、结果集分别怎么比，避免了模型“自由发挥”导致误判。
- **输出格式锁定为JSON**：这是最重要的！强制模型输出结构化的数据，方便我们后续的工作流节点（比如代码节点）进行解析和汇总。如果让模型自由发挥，输出一段文本，我们后面就很难自动化处理了。
- **使用变量**：`{{current_question}}` 和 `{{current_answer}}` 就是从上一步代码节点传过来的值，Dify会自动替换。

在实际使用中，你可能需要将数据库连接信息（如主机、端口、用户名、密码、数据库名）通过Dify的“密钥”功能进行管理，然后在提示词中通过 `{{#secrets.DB_HOST#}}` 这样的方式引用，这样既安全又灵活。

## 6. 结果汇总与自动化报告生成

LLM节点对每一个测试用例都给出了JSON格式的批改结果。现在，我们需要在迭代循环的**外部**，把这些零散的结果收集起来，组装成一份完整的、人类可读的测试报告。

Dify的“迭代循环”节点有一个非常实用的特性：它会自动收集循环体内所有节点的输出，并在循环结束后，将这些输出**汇总成一个列表**。我们正好可以利用这个特性。

具体操作是：
1.  确保LLM节点的输出（那个JSON对象）是迭代循环中最后一个节点的输出，这样它就会成为本次循环的“最终输出”。
2.  在迭代循环节点之后，连接一个新的“代码”节点。这个节点将接收一个列表（假设我们将其命名为 `all_results`），这个列表里的每一个元素，就是一次循环输出的JSON对象。
3.  在这个代码节点里，我们编写Python脚本，来分析和汇总 `all_results`。

这个汇总脚本可以做很多事情，我通常会让它完成以下工作：
- 统计总用例数、通过数、失败数，计算通过率。
- 将失败用例的详细信息（ID、SQL、期望结果、实际结果、失败原因）单独提取出来，方便重点排查。
- 将汇总结果格式化成一份清晰的Markdown报告。

```python
def main(all_results: list) -> dict:
    """
    汇总所有测试用例的结果，生成测试报告。
    输入: all_results, 一个字典列表，每个字典是一次LLM批改的输出。
    输出: 一个包含汇总报告和原始数据的字典。
    """
    if not all_results:
        return {"report": "错误：未接收到任何测试结果。", "summary": {}, "details": []}

    total = len(all_results)
    pass_count = sum(1 for item in all_results if isinstance(item, dict) and item.get("judgment") == "[PASS]")
    fail_count = total - pass_count
    pass_rate = (pass_count / total * 100) if total > 0 else 0

    # 提取失败用例的详细信息
    failed_cases = []
    for case in all_results:
        if isinstance(case, dict) and case.get("judgment") == "[FAIL]":
            failed_cases.append({
                "id": case.get("test_id", "N/A"),
                "sql": case.get("sql_query", "N/A"),
                "expected": case.get("expected_result", "N/A"),
                "actual": case.get("actual_result", "N/A"),
                "reason": case.get("reason", "N/A")
            })

    # 生成Markdown格式的详细报告
    report_lines = []
    report_lines.append(f"# 数据库调优自动化测试报告\n")
    report_lines.append(f"**生成时间**：{datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n")
    report_lines.append(f"## 执行摘要\n")
    report_lines.append(f"- **总测试用例数**：{total}\n")
    report_lines.append(f"- **通过用例数**：{pass_count}\n")
    report_lines.append(f"- **失败用例数**：{fail_count}\n")
    report_lines.append(f"- **通过率**：{pass_rate:.2f}%\n")

    if failed_cases:
        report_lines.append(f"## 失败用例详情\n")
        for i, fc in enumerate(failed_cases, 1):
            report_lines.append(f"### 失败用例 {i}: ID - {fc['id']}\n")
            report_lines.append(f"**SQL查询**：\n```sql\n{fc['sql']}\n```\n")
            report_lines.append(f"**期望结果**：`{fc['expected']}`\n")
            report_lines.append(f"**实际结果**：`{fc['actual']}`\n")
            report_lines.append(f"**失败原因**：{fc['reason']}\n")
            report_lines.append("---\n")
    else:
        report_lines.append("## 恭喜！所有测试用例均已通过。\n")

    # 将报告合并为一个字符串
    final_report = "\n".join(report_lines)

    # 返回结果，可以同时包含报告文本和结构化数据，供后续节点使用
    return {
        "test_report_markdown": final_report,
        "summary": {
            "total": total,
            "passed": pass_count,
            "failed": fail_count,
            "pass_rate": pass_rate
        },
        "failed_details": failed_cases
    }

最后，你可以再连接一个“文本”节点，将 test_report_markdown 的内容展示给最终用户，或者连接一个“下载”节点，让用户将这份Markdown报告保存为文件。整个自动化验证流水线，至此就全部搭建完成了。

7. 避坑指南与性能优化建议

走通了整个流程，并不意味着高枕无忧。在实际部署和使用中，还有一些细节需要注意，这些坑我都替你踩过了。

关于大模型的选择与成本：如果你用GPT-4这类模型，精度高，但成本也高，尤其是测试用例很多的时候。对于内部测试，可以考虑使用成本更低的模型，如GPT-3.5-Turbo、Claude Haiku，甚至是开源的DeepSeek、Qwen等通过API提供的模型。关键在于提示词要写得更精确，必要时在上下文中提供数据库表结构（Schema），帮助模型更好地理解SQL。实测下来，对于简单的查询验证，3.5级别的模型完全够用，能省下不少钱。

处理超时与长文本：复杂的SQL查询可能返回大量数据，超出模型的上下文限制或导致响应超时。在提示词中，可以要求模型“只返回前N行结果进行比对”，或者对聚合函数（如COUNT， SUM）的结果进行验证。同时，在Dify的工作流设置中，适当调整LLM节点的超时时间。

数据库连接安全：切记！不要在提示词里明文写数据库密码。 一定要用Dify的“密钥”功能。将数据库连接字符串或各部分参数（主机、用户名、密码等）保存为密钥，然后在提示词中用 {{#secrets.XXX#}} 引用。这样既安全，也方便在不同环境（测试、生产）间切换配置。

迭代循环的稳定性：当测试用例很多（比如上千条）时，让工作流一次性跑完所有循环，可能会遇到网络波动或模型偶尔的抽风导致个别循环失败，从而让整个任务失败。一个更稳健的策略是分批次处理。你可以在第一个解析代码节点里，把大的列表拆分成多个小块（比如每50条一个批次），然后逐个批次地送入迭代循环。虽然配置稍麻烦，但容错性更高。

结果的持久化：Dify工作流默认不保存每次运行的详细结果。对于重要的调优验证，你可能需要将每次的测试报告和原始结果保存下来，以便追溯。可以在最后的汇总代码节点里，增加将结果写入数据库（如SQLite、MySQL）或发送到Webhook（如钉钉、企业微信、Slack）的代码，实现自动归档和通知。

最后，也是最重要的一点：这个自动化系统是用来辅助你、解放你的，而不是完全取代你。 对于它判为“失败”的用例，尤其是涉及复杂逻辑或数据一致性校验的，最后仍需人工复核。但它能帮你过滤掉95%以上显而易见的“正确”和“错误”，让你把宝贵的精力集中在那些真正需要思考的边界案例上。从我自己的使用经验来看，自从搭建了这个流水线，每次数据调优后的回归测试从一项令人望而生畏的“体力活”，变成了一键触发、喝杯咖啡等报告的轻松事，效率和信心都得到了巨大的提升。