012-kaopeilian/知识库/开发记录/Dify系统对接分析报告.md

考培练系统与Dify平台对接深度分析报告

目录

1. 系统概述
2. Dify API接口分析
3. 前端页面对接实现
4. 业务流程分析
5. 技术架构图
6. 配置参数详解
7. 数据流向分析
8. 错误处理机制
9. 性能优化建议

系统概述

本考培练系统是一个基于 Python + Vue3 + MySQL + FastAPI 架构的智能教育平台，与两个主要的AI平台进行深度对接：

• Dify平台：用于动态题目生成和知识提取
• Coze平台：用于AI陪练和智能对话

核心功能模块

• 动态考试题目生成（基于Dify工作流）
• 知识点提取与分析（基于Dify工作流）
• AI智能陪练（基于Coze智能体）
• 三轮考试机制（错题重练）

Dify API接口分析

1. 主要接口端点

系统中使用了 1个核心Dify API端点：

POST https://aiedu.ireborn.com.cn/v1/workflows/run

2. 使用的工作流Token

系统中发现了 2个不同的工作流Token：

2.1 动态题目生成工作流

• Token: app-tDlrmXyS9NtWCShsOx5FH49L
• 用途: 根据考试ID和错题信息生成动态题目
• 文件位置: ExamsSystem/frontend/src/views/system/exams/start_exams.vue

2.2 知识提取工作流

• Token: app-LZhZcMO6CiriLMOLB2PwUGHx
• 用途: 从考试附件中提取知识点
• 文件位置: ExamsSystem/frontend/src/views/system/exams/index.vue

3. API请求参数详解

3.1 动态题目生成API参数

const payload = {
    inputs: {
        examsId: examId,        // 考试ID（必需）
        error: errorNums        // 错题编号（可选，用于第二轮、第三轮）
    },
    response_mode: "blocking", // 同步模式
    user: "abc-123"           // 用户标识
};

参数说明：

• examsId: 当前考试的唯一标识符，用于工作流识别要生成哪个考试的题目
• error: 错题编号字符串，格式为逗号分隔的知识点编号，用于生成针对性的错题练习
• response_mode: 固定为"blocking"，表示同步等待工作流执行完成
• user: 用户标识，固定为"abc-123"

3.2 知识提取API参数

const payload = {
    inputs: {
        examsTitle: exams_title,  // 考试标题
        file: [file],             // 文件信息数组
        examsId: row.id           // 考试ID
    },
    response_mode: "blocking",
    user: "abc-123"
};

// 文件对象结构
const file = {
    transfer_method: "remote_url",
    url: fileUrl,                 // 完整的文件URL
    type: "document"              // 文件类型
};

参数说明：

• examsTitle: 考试名称，帮助工作流理解文档内容的上下文
• file: 文件信息数组，支持PDF等文档格式的知识提取
• transfer_method: 固定为"remote_url"，表示通过URL方式传递文件
• url: 文件的完整访问URL，支持相对路径自动补全为绝对路径
• type: 固定为"document"，表示文档类型

4. API响应数据结构

4.1 成功响应结构

{
    data: {
        status: "succeeded",        // 执行状态
        outputs: {
            result: [...]           // 工作流输出结果
        }
    }
}

4.2 题目数据结构

动态题目生成的响应数据中，result字段包含题目数组：

[
    {
        topic: {
            title: "题目内容",      // 题目文本
            options: {
                opt1: "选项A",
                opt2: "选项B", 
                opt3: "选项C",
                opt4: "选项D"
            }
        },
        correct: "A",              // 正确答案
        analysis: "解析内容",       // 题目解析
        know_title: "知识点编号"    // 知识点标识
    }
]

前端页面对接实现

1. 核心页面文件

1.1 考试开始页面 (start_exams.vue)

• 路径: ExamsSystem/frontend/src/views/system/exams/start_exams.vue
• 功能: 动态题目生成、三轮考试机制、错题统计
• 关键函数: callDifyWorkflow()

1.2 考试管理页面 (index.vue)

• 路径: ExamsSystem/frontend/src/views/system/exams/index.vue
• 功能: 知识提取、考试管理
• 关键函数: update_know()

1.3 AI陪练页面 (training.vue)

• 路径: ExamsSystem/frontend/src/views/system/exams/training.vue
• 功能: 嵌入Coze聊天界面
• 实现方式: iframe嵌入

2. 前端调用实现

2.1 动态题目生成调用

async function callDifyWorkflow(error = '') {
    loading.value = true;
    const url = "https://aiedu.ireborn.com.cn/v1/workflows/run";
    const token = 'app-tDlrmXyS9NtWCShsOx5FH49L';
    
    const payload = {
        inputs: { examsId: examId },
        response_mode: "blocking",
        user: "abc-123"
    };
    
    // 错题重练时添加错题参数
    if (error) {
        payload.inputs.error = error;
    }

    try {
        const res = await fetch(url, {
            method: "POST",
            headers: {
                "Authorization": `Bearer ${token}`,
                "Content-Type": "application/json"
            },
            body: JSON.stringify(payload)
        });
        
        const data = await res.json();
        if (data.data.status != 'succeeded') throw new Error("请求失败");
        
        questions.value = data.data.outputs.result;
        loading.value = false;
        return data;
    } catch (err) {
        console.error("Dify 工作流调用异常:", err);
        loading.value = false;
        return null;
    }
}

2.2 知识提取调用

async function update_know(row) {
    // 获取考试附件信息
    const exams_title = row.title || '';
    const fileList = Array.isArray(row.attachmentList) ? row.attachmentList : [];
    
    if (!fileList.length) {
        proxy.$modal.msgWarning("该考试没有附件，无法提取知识！");
        return;
    }
    
    // 构建文件对象
    const fileUrl = fileList[0].fileUrl || fileList[0].url || '';
    const file = {
        transfer_method: "remote_url",
        url: fileUrl.startsWith('http') ? fileUrl : `https://aiedu.ireborn.com.cn${fileUrl}`,
        type: "document"
    };

    const payload = {
        inputs: {
            examsTitle: exams_title,
            file: [file],
            examsId: row.id
        },
        response_mode: "blocking",
        user: "abc-123"
    };

    const token = "app-LZhZcMO6CiriLMOLB2PwUGHx";
    const url = "https://aiedu.ireborn.com.cn/v1/workflows/run";

    proxy.$modal.loading("正在提取知识，请稍候...");
    try {
        const res = await fetch(url, {
            method: "POST",
            headers: {
                "Authorization": `Bearer ${token}`,
                "Content-Type": "application/json"
            },
            body: JSON.stringify(payload)
        });
        
        if (!res.ok) {
            proxy.$modal.msgError("知识提取失败！");
            return;
        }
        
        const data = await res.json();
        proxy.$modal.msgSuccess("知识提取成功！");
        console.log("Dify知识提取结果:", data);
    } catch (err) {
        proxy.$modal.closeLoading();
        proxy.$modal.msgError("知识提取异常！");
        console.error("Dify知识提取异常:", err);
    }
}

3. 前端状态管理

3.1 考试状态管理

// 核心状态变量
const questions = ref([]);          // 题目数组
const loading = ref(true);          // 加载状态
const currentIndex = ref(0);        // 当前题目索引
const selected = ref('');           // 选中答案
const answered = ref(false);        // 是否已答题
const score = ref(0);              // 当前分数
const wrongQuestions = ref([]);     // 错题记录
const round = ref(1);              // 当前轮次 (1,2,3)

// 三轮成绩记录
const firstRoundScore = ref(0);
const firstRoundTime = ref(null);
const secondRoundScore = ref(0);
const secondRoundTime = ref(null);
const thirdRoundScore = ref(0);
const thirdRoundTime = ref(null);

3.2 轮次流转逻辑

// 第二轮：基于第一轮错题
function restartWithWrongQuestions() {
    const errorNums = wrongQuestions.value.map(item => item.title).join(',');
    // 重置状态
    currentIndex.value = 0;
    score.value = 0;
    wrongQuestions.value = [];
    round.value = 2;
    // 调用Dify生成针对性题目
    callDifyWorkflow(errorNums);
}

// 第三轮：基于第二轮错题  
function restartWithThirdQuestions() {
    const errorNums = wrongQuestions.value.map(item => item.title).join(',');
    // 重置状态
    currentIndex.value = 0;
    score.value = 0;
    thirdWrongQuestions.value = [...wrongQuestions.value];
    wrongQuestions.value = [];
    round.value = 3;
    // 调用Dify生成针对性题目
    callDifyWorkflow(errorNums);
}

业务流程分析

1. 动态考试流程

graph TD
    A[用户选择考试] --> B[获取考试ID]
    B --> C[调用Dify工作流]
    C --> D[生成第一轮题目]
    D --> E[用户答题]
    E --> F[记录错题]
    F --> G{是否完成所有题目}
    G -->|否| E
    G -->|是| H[显示第一轮成绩]
    H --> I{用户选择第二轮}
    I -->|是| J[传递错题信息给Dify]
    J --> K[生成第二轮针对性题目]
    K --> L[用户答题]
    L --> M[记录错题]
    M --> N{是否完成所有题目}
    N -->|否| L
    N -->|是| O[显示第二轮成绩]
    O --> P{用户选择第三轮}
    P -->|是| Q[传递第二轮错题给Dify]
    Q --> R[生成第三轮题目]
    R --> S[完成三轮考试]
    S --> T[保存最终成绩]

2. 知识提取流程

graph TD
    A[管理员上传考试附件] --> B[点击知识提取按钮]
    B --> C[获取附件URL]
    C --> D[构建文件对象]
    D --> E[调用Dify知识提取工作流]
    E --> F[Dify处理PDF文档]
    F --> G[提取知识点]
    G --> H[返回提取结果]
    H --> I[前端显示成功消息]

3. AI陪练流程

graph TD
    A[用户进入陪练页面] --> B[iframe加载Coze聊天界面]
    B --> C[用户发送语音/文本]
    C --> D[Coze智能体处理]
    D --> E[返回AI回复]
    E --> F[支持语音合成]
    F --> G[用户继续对话]
    G --> C

技术架构图

1. 整体架构

graph TB
    subgraph "前端层 (Vue3)"
        A1[考试管理页面]
        A2[动态考试页面]  
        A3[AI陪练页面]
    end
    
    subgraph "后端层 (FastAPI)"
        B1[考试管理API]
        B2[成绩管理API]
        B3[文件管理API]
    end
    
    subgraph "AI平台层"
        C1[Dify工作流]
        C2[Coze智能体]
    end
    
    subgraph "数据层"
        D1[MySQL数据库]
        D2[文件存储]
    end
    
    A1 --> B1
    A2 --> C1
    A3 --> C2
    A2 --> B2
    B1 --> D1
    B2 --> D1
    B3 --> D2
    C1 --> D2

2. Dify集成架构

graph LR
    subgraph "前端"
        A[Vue组件]
    end
    
    subgraph "Dify平台"
        B[工作流引擎]
        C[题目生成工作流]
        D[知识提取工作流]
    end
    
    A -->|HTTP POST| B
    B --> C
    B --> D
    C -->|题目数据| A
    D -->|知识点数据| A

配置参数详解

1. 系统配置

1.1 域名配置

• 主域名: https://aiedu.ireborn.com.cn
• API端点: /v1/workflows/run
• 文件服务: /dev-api/profile/upload/

1.2 工作流配置

功能	Token	Bot ID	用途
题目生成	app-tDlrmXyS9NtWCShsOx5FH49L	-	根据考试ID和错题生成动态题目
知识提取	app-LZhZcMO6CiriLMOLB2PwUGHx	-	从PDF文档中提取知识点
高情商回复	-	7509380917472280617	AI智能回复
咨询师陪练	-	7509379008556089379	语音陪练
动态考题	-	7509379046204162074	动态题目生成

2. 环境配置

2.1 前端配置 (vite.config.js)

server: {
    host: '0.0.0.0',
    port: 80,
    proxy: {
        '/dev-api': {
            target: 'https://aiedu.ireborn.com.cn',
            changeOrigin: true,
            rewrite: (p) => p.replace(/^\/dev-api/, '')
        }
    }
}

2.2 后端配置 (config/env.py)

app_host: str = 'https://aiedu.ireborn.com.cn/'

数据流向分析

1. 题目生成数据流

用户操作 → Vue组件状态 → Dify API调用 → 工作流处理 → 题目数据返回 → 前端渲染

详细流程：

1. 用户点击开始考试
2. 获取URL参数中的examId
3. 调用callDifyWorkflow(examId)
4. 发送POST请求到Dify工作流
5. 工作流根据examsId生成题目
6. 返回JSON格式的题目数组
7. 前端解析数据并渲染题目界面

2. 错题重练数据流

错题收集 → 错题编号拼接 → Dify API调用(带error参数) → 针对性题目生成 → 前端渲染

详细流程：

1. 第一轮答题过程中收集错题
2. 将错题的know_title字段拼接成字符串
3. 调用callDifyWorkflow(errorNums)
4. Dify工作流根据错题信息生成针对性题目
5. 返回专门针对薄弱知识点的题目
6. 前端进入第二轮/第三轮答题模式

3. 知识提取数据流

文件上传 → 附件URL获取 → Dify API调用 → PDF解析 → 知识点提取 → 结果返回

详细流程：

1. 管理员在考试管理页面上传PDF附件
2. 系统生成文件访问URL
3. 点击"知识提取"按钮触发update_know()
4. 构建包含文件URL的请求参数
5. 调用Dify知识提取工作流
6. 工作流下载并解析PDF文档
7. 提取关键知识点并返回结果

错误处理机制

1. API调用错误处理

1.1 网络错误处理

try {
    const res = await fetch(url, options);
    const data = await res.json();
    // 处理成功响应
} catch (err) {
    console.error("Dify 工作流调用异常:", err);
    loading.value = false;
    return null;
}

1.2 业务错误处理

if (data.data.status != 'succeeded') {
    throw new Error("请求失败");
}

1.3 用户提示机制

// 成功提示
proxy.$modal.msgSuccess("知识提取成功！");

// 警告提示  
proxy.$modal.msgWarning("该考试没有附件，无法提取知识！");

// 错误提示
proxy.$modal.msgError("知识提取失败！");

// 加载提示
proxy.$modal.loading("正在提取知识，请稍候...");
proxy.$modal.closeLoading();

2. 数据验证机制

2.1 前端验证

• 检查考试ID是否存在
• 验证附件列表是否为空
• 确认URL格式正确性

2.2 响应数据验证

• 检查data.data.status是否为"succeeded"
• 验证data.data.outputs.result是否存在
• 确保题目数据结构完整

性能优化建议

1. 前端优化

1.1 请求优化

• 缓存机制: 对相同考试ID的题目进行本地缓存
• 请求去重: 防止用户快速点击导致的重复请求
• 超时处理: 设置合理的请求超时时间

1.2 用户体验优化

• 加载状态: 显示详细的加载进度和状态
• 错误重试: 提供手动重试机制
• 离线支持: 缓存已生成的题目支持离线答题

2. 后端优化

2.1 API性能

• 连接池: 使用HTTP连接池减少连接开销
• 异步处理: 对于知识提取等耗时操作使用异步处理
• 结果缓存: 缓存Dify工作流的执行结果

2.2 监控告警

• API监控: 监控Dify API的响应时间和成功率
• 错误日志: 记录详细的错误日志便于问题排查
• 性能指标: 统计题目生成时间和知识提取效率

3. Dify工作流优化

3.1 工作流设计

• 参数验证: 在工作流中添加输入参数验证
• 错误处理: 完善工作流内部的错误处理逻辑
• 性能调优: 优化工作流的执行效率

3.2 资源管理

• 并发控制: 控制同时执行的工作流数量
• 资源限制: 设置合理的内存和CPU使用限制
• 成本优化: 监控和优化AI模型的调用成本

总结

本考培练系统通过与Dify平台的深度对接，实现了智能化的题目生成和知识提取功能。系统采用了成熟的技术架构，具备良好的扩展性和可维护性。主要特点包括：

1. 智能题目生成: 基于考试内容和学员错题情况动态生成个性化题目
2. 三轮考试机制: 通过多轮练习帮助学员巩固薄弱知识点
3. 知识自动提取: 从PDF文档中自动提取关键知识点
4. AI智能陪练: 结合Coze平台提供语音陪练功能

系统在实现上注重用户体验和错误处理，具备较强的实用性和稳定性。建议在后续开发中进一步优化性能和扩展功能模块。

---

文档版本: v1.0
生成时间: 2025年9月20日
分析范围: ExamsSystem、coze-chat-backend、coze-chat-frontend模块