| # DataFlow Agent 快速入门指南 |
|
|
| 本指南将帮助您快速上手 DataFlow Agent 平台的5个核心功能模块。 |
|
|
| ## 目录 |
|
|
| 1. [管线推荐](#1-管线推荐) |
| 2. [算子编写](#2-算子编写) |
| 3. [手动编排](#3-手动编排) |
| 4. [算子复用/提示词优化](#4-算子复用提示词优化) |
| 5. [Web Search/数据采集](#5-web-search数据采集) |
|
|
| --- |
|
|
| ## 1. 管线推荐 |
|
|
| ### 功能概述 |
| 根据用户的自然语言描述，自动推荐并生成合适的 DataFlow Pipeline，包括算子选择、参数配置和代码生成。 |
|
|
| ### 使用场景 |
| - 快速构建数据处理流程 |
| - 不熟悉具体算子时的智能推荐 |
| - 自动化 Pipeline 生成 |
|
|
| ### 输入参数 |
|
|
| #### 基础配置 |
| - **目标描述** (必需) |
| - 描述您想要实现的数据处理目标 |
| - 示例：`"给我随意符合逻辑的5个算子，过滤，去重！"` |
| - 示例：`"对文本数据进行清洗、去重、分类"` |
|
|
| - **输入 JSONL 文件路径** (必需) |
| - 用于测试 Pipeline 的数据文件 |
| - 格式：每行一个 JSON 对象 |
| - 默认：`{项目根目录}/tests/test.jsonl` |
|
|
| - **Session ID** |
| - 会话标识符，用于缓存和追踪 |
| - 默认：`"default"` |
|
|
| #### API 配置 |
|
|
| **主要模型配置** |
| - **Chat API URL**: LLM 服务地址 |
| - 默认：`http://123.129.219.111:3000/v1/` |
| - **API Key**: 访问密钥 |
| - **模型名称**: 如 `gpt-4o`, `qwen-max`, `llama3` 等 |
| - 默认：`gpt-4o` |
|
|
| **嵌入模型配置** |
| - **Embedding API URL**: 嵌入模型服务地址（可选，留空则使用主要 API） |
| - **Embedding 模型名称**: 如 `text-embedding-3-small` |
|
|
| #### 调试配置 |
| - **启用调试模式**: 是否启用自动调试和修复 |
| - **调试模式执行次数**: 1-10 次，默认 2 次 |
|
|
| ### 输出结果 |
|
|
| #### 1. Pipeline Code (生成的代码) |
| ```python |
| # 自动生成的 Python 代码 |
| # 包含完整的 Pipeline 定义和执行逻辑 |
| ``` |
|
|
| #### 2. Execution Log (执行日志) |
| - Pipeline 执行过程的详细日志 |
| - 包含每个算子的执行状态 |
| - 错误信息和调试信息 |
|
|
| #### 3. Agent Results (Agent 执行结果) |
| ```json |
| { |
| "recommender": {...}, |
| "pipeline_builder": {...}, |
| "operator_executor": {...} |
| } |
| ``` |
| - 各个 Agent 节点的详细执行结果 |
| - 包含推荐的算子列表、构建过程等 |
|
|
| ### 使用步骤 |
|
|
| 1. 在"目标描述"框中输入您的需求 |
| 2. 配置 API 信息（URL、Key、模型） |
| 3. （可选）配置嵌入模型和调试选项 |
| 4. 点击"生成 Pipeline"按钮 |
| 5. 查看生成的代码和执行结果 |
|
|
| --- |
|
|
| ## 2. 算子编写 |
|
|
| ### 功能概述 |
| 根据用户需求自动生成新的 DataFlow 算子代码，包括算子实现、测试代码和调试。 |
|
|
| ### 使用场景 |
| - 创建自定义数据处理算子 |
| - 扩展 DataFlow 功能 |
| - 快速原型开发 |
|
|
| ### 输入参数 |
|
|
| #### 基础配置 |
| - **目标描述** (必需) |
| - 描述算子的功能和用途 |
| - 示例：`"创建一个算子，用于对文本进行情感分析"` |
| - 示例：`"实现一个数据去重算子，支持多字段组合去重"` |
|
|
| - **算子类别** |
| - 算子所属类别，用于匹配相似算子作为参考 |
| - 默认：`"Default"` |
| - 可选：`"filter"`, `"mapper"`, `"aggregator"` 等 |
|
|
| - **测试数据文件路径 (JSONL)** |
| - 用于测试算子的数据文件 |
| - 默认：`{项目根目录}/tests/test.jsonl` |
|
|
| #### API 配置 |
| - **Chat API URL**: LLM 服务地址 |
| - **API Key**: 访问密钥（留空则使用环境变量 `DF_API_KEY`） |
| - **模型名称**: 默认 `gpt-4o` |
|
|
| #### 高级配置 |
| - **输出语言**: `en` (英文) 或 `zh` (中文) |
| - **启用调试模式**: 自动执行并修复代码错误 |
| - **最大调试轮次**: 1-10 次，默认 3 次 |
| - **输出文件路径**: 保存生成代码的位置（可选） |
|
|
| ### 输出结果 |
|
|
| #### 1. 生成的代码 |
| ```python |
| # 完整的算子实现代码 |
| class YourOperator(Operator): |
| def __init__(self, ...): |
| ... |
| |
| def run(self, dataset, ...): |
| ... |
| ``` |
|
|
| #### 2. 匹配的算子 |
| ```json |
| [ |
| { |
| "op_name": "similar_operator_1", |
| "similarity": 0.85, |
| "description": "..." |
| } |
| ] |
| ``` |
| - 系统匹配到的相似算子列表 |
| - 用作参考和学习 |
|
|
| #### 3. 执行结果 |
| ```json |
| { |
| "success": true, |
| "output": {...}, |
| "stderr": "", |
| "stdout": "..." |
| } |
| ``` |
| - 算子的执行状态 |
| - 输出数据预览 |
| - 错误信息（如有） |
|
|
| #### 4. 调试信息 |
| ```json |
| { |
| "round": 2, |
| "input_key": "text", |
| "available_keys": ["text", "label"], |
| "stdout": "...", |
| "stderr": "..." |
| } |
| ``` |
| - 调试过程的详细信息 |
| - 每轮调试的输入输出 |
|
|
| #### 5. Agent 结果 |
| - 各个 Agent 节点的执行详情 |
| - 包含匹配、编写、执行、调试等阶段 |
|
|
| #### 6. 执行日志 |
| - 完整的执行过程日志 |
| - 包含所有阶段的详细信息 |
|
|
| ### 使用步骤 |
|
|
| 1. 在"目标描述"中详细说明算子功能 |
| 2. 选择合适的算子类别 |
| 3. 配置 API 信息 |
| 4. （可选）启用调试模式以自动修复错误 |
| 5. 点击"生成算子"按钮 |
| 6. 查看生成的代码和测试结果 |
| 7. 如需修改，可调整参数后重新生成 |
|
|
| --- |
|
|
| ## 3. 手动编排 |
|
|
| ### 功能概述 |
| 通过可视化界面手动选择和组装算子，构建自定义 Pipeline，支持拖拽排序和参数配置。 |
|
|
| ### 使用场景 |
| - 精确控制 Pipeline 结构 |
| - 复用现有算子 |
| - 快速原型验证 |
| - 学习算子使用方法 |
|
|
| ### 输入参数 |
|
|
| #### API 和文件配置 |
| - **Chat API URL**: LLM 服务地址 |
| - **API Key**: 访问密钥 |
| - **模型名称**: 默认 `gpt-4o` |
| - **输入 JSONL 文件路径**: 测试数据文件 |
|
|
| #### 算子选择和配置 |
|
|
| **步骤 1: 选择算子** |
| 1. 从"算子分类"下拉框选择类别 |
| - 如：`filter`, `mapper`, `deduplicator` 等 |
| 2. 从"算子"下拉框选择具体算子 |
| - 系统会自动显示该算子的参数说明 |
|
|
| **步骤 2: 配置参数** |
|
|
| - **Prompt Template (可选)** |
| - 如果算子支持 Prompt 模板，会显示下拉选择器 |
| - 选择后自动更新到 `__init__()` 参数中 |
|
|
| - **`__init__()` 参数 (JSON 格式)** |
| ```json |
| { |
| "param1": "value1", |
| "param2": 123, |
| "prompt_template": "module.PromptClass" |
| } |
| ``` |
| - 算子初始化参数 |
| - 必须是有效的 JSON 对象 |
| |
| - **`run()` 参数 (JSON 格式)** |
| ```json |
| { |
| "input_key": "text", |
| "output_key": "processed_text", |
| "batch_size": 32 |
| } |
| ``` |
| - 算子运行时参数 |
| - 必须是有效的 JSON 对象 |
|
|
| **步骤 3: 添加到 Pipeline** |
| - 点击"➕ 添加算子到 Pipeline"按钮 |
| - 算子会被添加到 Pipeline 序列中 |
|
|
| **步骤 4: 调整顺序** |
| - 在 Pipeline 可视化区域，拖拽算子卡片调整顺序 |
| - 系统会自动重新编号 |
|
|
| **步骤 5: 自动链接** |
| - 系统会自动分析算子间的输入输出关系 |
| - 显示链接状态： |
| - 🔗 **已链接**: 输出键成功匹配到下一个算子的输入 |
| - ⚠️ **待处理**: 输入为空或未匹配 |
|
|
| ### 输出结果 |
|
|
| #### 1. 当前 Pipeline (可视化展示) |
| - 每个算子显示为卡片，包含： |
| - 步骤编号 |
| - 算子名称 |
| - `__init__()` 参数预览 |
| - `run()` 参数预览 |
| - 与上一步的连接状态 |
|
|
| #### 2. 当前 Pipeline (JSON 格式) |
| ```json |
| [ |
| { |
| "op_name": "TextCleanerOperator", |
| "init_params": {...}, |
| "run_params": {...}, |
| "_incoming_links": [ |
| { |
| "input_key": "text", |
| "value": "raw_text", |
| "output_keys": ["output"] |
| } |
| ] |
| } |
| ] |
| ``` |
|
|
| #### 3. 生成的代码 |
| ```python |
| # 完整的 Pipeline 执行代码 |
| from dataflow import Dataset |
| from dataflow.operators import * |
| |
| # 加载数据 |
| dataset = Dataset.load("input.jsonl") |
| |
| # 执行 Pipeline |
| dataset = TextCleanerOperator(...).run(dataset, ...) |
| dataset = DeduplicatorOperator(...).run(dataset, ...) |
| ... |
| |
| # 保存结果 |
| dataset.save("output.jsonl") |
| ``` |
|
|
| #### 4. 处理结果数据 (前 100 条) |
| ```json |
| [ |
| {"text": "processed text 1", "label": "A"}, |
| {"text": "processed text 2", "label": "B"}, |
| ... |
| ] |
| ``` |
|
|
| #### 5. 输出文件路径 |
| - 处理后数据的保存位置 |
|
|
| ### 使用步骤 |
|
|
| 1. 配置 API 信息和输入文件路径 |
| 2. 选择算子分类和具体算子 |
| 3. 编辑 `__init__()` 和 `run()` 参数（JSON 格式） |
| 4. 点击"➕ 添加算子到 Pipeline" |
| 5. 重复步骤 2-4 添加更多算子 |
| 6. 拖拽调整算子顺序（可选） |
| 7. 检查自动链接状态，确保参数正确 |
| 8. 点击"🚀 运行 Pipeline" |
| 9. 查看生成的代码和执行结果 |
|
|
| ### 高级技巧 |
|
|
| - **清空 Pipeline**: 点击"🗑️ 清空 Pipeline"按钮 |
| - **参数复用**: 系统会自动将上一个算子的输出键链接到下一个算子的输入 |
| - **调试**: 如果执行失败，检查日志中的错误信息，调整参数后重试 |
|
|
| --- |
|
|
| ## 4. 算子复用/提示词优化 |
|
|
| ### 功能概述 |
| PromptAgent 前端，用于生成和优化算子的 Prompt 模板，支持多轮对话式改写和测试。 |
|
|
| ### 使用场景 |
| - 为算子创建高质量的 Prompt 模板 |
| - 优化现有 Prompt 的效果 |
| - 快速迭代 Prompt 设计 |
| - 生成测试代码和数据 |
|
|
| ### 输入参数 |
|
|
| #### 运行配置 |
| - **Chat API Base URL**: LLM 服务地址 |
| - 默认：`http://123.129.219.111:3000/v1/` |
| - **Chat API Key**: 访问密钥 |
| - **Model**: 模型名称，默认 `gpt-4o` |
| - **Language**: 提示词语言，`zh` (中文) 或 `en` (英文) |
|
|
| #### Prompt 配置 |
| - **任务描述** (必需) |
| - 详细描述 Prompt 要完成的任务 |
| - 示例：`"对用户输入的文本进行情感分析，判断是正面、负面还是中性"` |
| - 示例：`"将产品描述改写为更吸引人的营销文案"` |
|
|
| - **算子名称 (op-name)** (必需) |
| - Prompt 类的名称 |
| - 示例：`SentimentAnalysisPrompt` |
| - 示例：`MarketingCopywriterPrompt` |
|
|
| - **输出格式** (可选) |
| - 指定 Prompt 输出的格式 |
| - 示例： |
| ``` |
| { |
| "sentiment": "positive/negative/neutral", |
| "confidence": 0.95 |
| } |
| ``` |
| |
| - **参数列表** (可选) |
| - Prompt 模板需要的参数，用逗号、空格或换行分隔 |
| - 示例：`text, language, style` |
| - 示例： |
| ``` |
| input_text |
| target_audience |
| tone |
| ``` |
| |
| - **文件输出根路径** (可选) |
| - 保存生成文件的目录 |
| - 默认：`./pa_cache` |
|
|
| - **生成后删除测试文件** |
| - 是否在生成后删除测试文件（保留路径占位） |
| - 默认：启用 |
|
|
| ### 输出结果 |
|
|
| #### 1. Prompt 文件路径 |
| - 生成的 Prompt 模板文件位置 |
| - 示例：`./pa_cache/prompts/SentimentAnalysisPrompt.py` |
|
|
| #### 2. 测试数据文件路径 |
| - 自动生成的测试数据文件 |
| - 示例：`./pa_cache/test_data/test_data.jsonl` |
|
|
| #### 3. 测试代码文件路径 |
| - 自动生成的测试代码 |
| - 示例：`./pa_cache/tests/test_prompt.py` |
|
|
| #### 4. 测试数据预览 |
| ```json |
| [ |
| {"text": "这个产品真不错！", "language": "zh"}, |
| {"text": "质量太差了", "language": "zh"}, |
| {"text": "还可以吧", "language": "zh"} |
| ] |
| ``` |
|
|
| #### 5. 测试结果预览 |
| ```json |
| [ |
| { |
| "input": {"text": "这个产品真不错！"}, |
| "output": { |
| "sentiment": "positive", |
| "confidence": 0.92 |
| } |
| } |
| ] |
| ``` |
|
|
| #### 6. Prompt 代码预览 |
| ```python |
| from dataflow_agent.promptstemplates import PromptTemplate |
| |
| class SentimentAnalysisPrompt(PromptTemplate): |
| """情感分析 Prompt 模板""" |
| |
| def __init__(self): |
| super().__init__() |
| self.system_prompt = "你是一个情感分析专家..." |
| self.user_prompt_template = "请分析以下文本的情感：{text}" |
| |
| def format(self, text: str, **kwargs) -> str: |
| return self.user_prompt_template.format(text=text) |
| ``` |
|
|
| #### 7. 测试代码预览 |
| ```python |
| import json |
| from your_prompt import SentimentAnalysisPrompt |
| |
| # 加载测试数据 |
| with open("test_data.jsonl") as f: |
| test_data = [json.loads(line) for line in f] |
| |
| # 测试 Prompt |
| prompt = SentimentAnalysisPrompt() |
| for item in test_data: |
| result = prompt.format(**item) |
| print(result) |
| ``` |
|
|
| ### 多轮改写功能 |
|
|
| 在右侧对话区域，您可以： |
|
|
| 1. **查看初次生成结果** |
| - Prompt 代码 |
| - 测试结果 |
|
|
| 2. **提出改进建议** |
| - 在对话输入框中描述您希望如何修改 |
| - 示例： |
| - `"增加对讽刺语气的识别"` |
| - `"输出格式改为只返回 positive/negative/neutral 字符串"` |
| - `"添加置信度阈值，低于 0.7 时返回 uncertain"` |
|
|
| 3. **发送改写指令** |
| - 点击"发送改写指令"按钮 |
| - 系统会根据反馈重新生成 Prompt |
|
|
| 4. **迭代优化** |
| - 查看更新后的代码和测试结果 |
| - 继续提出改进建议 |
| - 重复直到满意 |
|
|
| 5. **清空会话** |
| - 点击"清空会话"按钮重新开始 |
|
|
| ### 使用步骤 |
|
|
| #### 初次生成 |
| 1. 配置 API 信息（URL、Key、模型） |
| 2. 填写任务描述、算子名称 |
| 3. （可选）指定输出格式和参数列表 |
| 4. 点击"生成 Prompt 模板"按钮 |
| 5. 查看生成的 Prompt 代码和测试结果 |
|
|
| #### 多轮优化 |
| 1. 在右侧对话框中输入改进建议 |
| 2. 点击"发送改写指令" |
| 3. 查看更新后的代码和测试结果 |
| 4. 重复步骤 1-3 直到满意 |
|
|
| #### 使用生成的 Prompt |
| 1. 从"Prompt 文件路径"获取文件位置 |
| 2. 将 Prompt 类导入到您的算子中 |
| 3. 在算子的 `__init__()` 中指定 `prompt_template` |
|
|
| --- |
|
|
| ## 5. Web Search/数据采集 |
|
|
| ### 功能概述 |
| 从网络（HuggingFace、Kaggle 等平台）自动采集数据集，并转换为统一格式，支持智能搜索、下载和数据清洗。 |
|
|
| ### 使用场景 |
| - 快速构建训练数据集 |
| - 收集特定领域的数据 |
| - 数据集格式转换 |
| - 批量下载和处理 |
|
|
| ### 输入参数 |
|
|
| #### 采集配置 |
| - **目标描述** (必需) |
| - 描述您想要收集的数据类型 |
| - 示例：`"收集 Python 代码示例的数据集"` |
| - 示例：`"收集中文对话数据，用于训练聊天机器人"` |
| - 示例：`"收集图像分类数据集，包含猫和狗的图片"` |
|
|
| - **数据类别** |
| - `PT`: 预训练数据（Pre-Training） |
| - `SFT`: 监督微调数据（Supervised Fine-Tuning） |
| - 默认：`SFT` |
|
|
| - **数据集数量上限（每关键词）** |
| - 每个搜索关键词返回的数据集数量 |
| - 范围：1-50 |
| - 默认：5 |
| - 注意：仅用于参考，实际数量可能因搜索结果而异 |
|
|
| - **数据集大小范围** |
| - 筛选数据集的大小范围 |
| - 选项： |
| - `n<1K`: 小于 1000 条 |
| - `1K<n<10K`: 1000-10000 条 |
| - `10K<n<100K`: 10000-100000 条 |
| - `100K<n<1M`: 100000-1000000 条 |
| - `n>1M`: 大于 1000000 条 |
| - 默认：`1K<n<10K` |
|
|
| - **下载子任务上限** |
| - 限制最终执行的下载任务数量 |
| - 留空表示不限制 |
| - 用于控制下载规模和时间 |
|
|
| - **最大数据集大小** |
| - 单个数据集的大小上限 |
| - 输入数值后选择单位（B/KB/MB/GB/TB） |
| - 留空表示不限制 |
|
|
| - **下载目录** |
| - 数据保存的根目录 |
| - 默认：`downloaded_data` |
|
|
| - **提示词语言** |
| - `zh`: 中文 |
| - `en`: 英文 |
| - 默认：`zh` |
|
|
| #### LLM 配置 |
| - **CHAT_API_URL**: LLM 服务地址 |
| - 默认：`http://123.129.219.111:3000/v1/chat/completions` |
| - **CHAT_API_KEY**: 访问密钥 |
| - **CHAT_MODEL**: 模型名称 |
| - 默认：`deepseek-chat` |
| |
| #### 其他环境配置 |
| - **HF_ENDPOINT**: HuggingFace 镜像地址 |
| - 默认：`https://hf-mirror.com` |
| - **KAGGLE_USERNAME**: Kaggle 用户名 |
| - **KAGGLE_KEY**: Kaggle API 密钥 |
| - **TAVILY_API_KEY**: Tavily 搜索 API 密钥 |
|
|
| #### RAG 配置 |
| - **RAG_EBD_MODEL**: 嵌入模型名称 |
| - 默认：`text-embedding-3-large` |
| - **RAG_API_URL**: RAG 服务地址 |
| - **RAG_API_KEY**: RAG API 密钥 |
|
|
| #### 高级配置（可折叠） |
|
|
| **网页采集高级配置** |
| - **下载任务最大循环次数**: 1-50，默认 10 |
| - 控制每个下载任务的最大重试次数 |
| - **研究阶段最大循环次数**: 1-50，默认 15 |
| - research 阶段的最大循环次数，允许访问更多网站 |
| - **搜索引擎**: `tavily` / `duckduckgo` / `jina` |
| - 默认：`tavily` |
| - **使用 Jina Reader**: 是否使用 Jina Reader 提取网页内容 |
| - 默认：启用 |
| - 优点：快速、结构化（Markdown 格式） |
| - **启用 RAG 增强**: 是否使用 RAG 精炼内容 |
| - 默认：启用 |
| - **并行处理页面数**: 1-20，默认 5 |
| - 并行处理的页面数量 |
| - 建议：3-10（根据网络和机器性能调整） |
| - **禁用缓存**: 是否禁用 HuggingFace 和 Kaggle 缓存 |
| - 默认：启用 |
| - 启用后使用临时目录，下载后自动清理 |
| - **临时目录**: 自定义临时目录路径 |
| - 留空则使用默认临时目录 |
|
|
| **数据转换高级配置** |
| - **转换模型温度**: 0.0-2.0，默认 0.0 |
| - 数据转换时的模型温度参数 |
| - **转换最大 Token 数**: 512-8192，默认 4096 |
| - 数据转换时的最大 token 数 |
| - **最大采样长度（字符）**: 50-1000，默认 200 |
| - 每个字段的最大采样长度 |
| - **采样记录数量**: 1-10，默认 3 |
| - 用于分析的采样记录数量 |
|
|
| ### 输出结果 |
|
|
| #### 1. 执行日志（实时流式输出） |
| ``` |
| ============================================================ |
| 开始执行网页采集与转换工作流 |
| ============================================================ |
| 目标: 收集 Python 代码示例的数据集 |
| 类别: SFT |
| 下载目录: downloaded_data |
| |
| 【网页采集配置】 |
| - 搜索引擎: tavily |
| - 下载子任务上限: 不限制 |
| - 任务最大循环次数: 10 |
| - 研究阶段最大循环次数: 15 |
| - 使用 Jina Reader: 是 |
| - 启用 RAG: 是 |
| - 并行页面数: 5 |
| - 禁用缓存: 是 |
| |
| 【数据转换配置】 |
| - 模型温度: 0.0 |
| - 最大 Token 数: 4096 |
| - 最大采样长度: 200 |
| - 采样记录数: 3 |
| |
| 数据集大小限制: 不限制 |
| ============================================================ |
| |
| 2025-01-23 10:00:00 [INFO] 开始搜索数据集... |
| 2025-01-23 10:00:05 [INFO] 找到 15 个候选数据集 |
| 2025-01-23 10:00:10 [INFO] 开始下载数据集 1/5... |
| 2025-01-23 10:01:00 [INFO] 数据集 1 下载完成 |
| ... |
| 2025-01-23 10:15:00 [INFO] 开始数据转换... |
| 2025-01-23 10:20:00 [INFO] 数据转换完成 |
| 流程执行完成！ |
| ``` |
| |
| #### 2. 结果摘要 |
| ```json |
| { |
| "download_dir": "downloaded_data", |
| "processed_output": "downloaded_data/processed_output", |
| "category": "SFT", |
| "language": "zh", |
| "chat_model": "deepseek-chat", |
| "max_download_subtasks": null, |
| "max_dataset_size_bytes": null, |
| "max_dataset_size_unit": null, |
| "max_dataset_size_value": null |
| } |
| ``` |
| |
| ### 输出文件结构 |
| |
| ``` |
| downloaded_data/ |
| ├── raw/ # 原始下载的数据 |
| │ ├── dataset_1/ |
| │ │ ├── data.jsonl |
| │ │ └── metadata.json |
| │ ├── dataset_2/ |
| │ └── ... |
| └── processed_output/ # 转换后的统一格式数据 |
| ├── combined.jsonl # 合并后的数据 |
| ├── train.jsonl # 训练集（如果分割） |
| ├── validation.jsonl # 验证集（如果分割） |
| └── metadata.json # 元数据信息 |
| ``` |
| |
| ### 使用步骤 |
|
|
| #### 基础使用 |
| 1. 在"目标描述"中详细说明要收集的数据类型 |
| 2. 选择数据类别（PT 或 SFT） |
| 3. 配置数据集数量和大小限制 |
| 4. 配置 LLM API 信息 |
| 5. （可选）配置 Kaggle、Tavily 等服务的密钥 |
| 6. 点击"开始网页采集与转换"按钮 |
| 7. 实时查看执行日志 |
| 8. 等待完成后查看结果摘要 |
| 9. 在下载目录中查看采集的数据 |
|
|
| #### 高级使用 |
| 1. 展开"⚙️ 高级配置"区域 |
| 2. 根据需求调整： |
| - 搜索引擎选择 |
| - 并行处理数量 |
| - 缓存策略 |
| - 数据转换参数 |
| 3. 执行采集任务 |
| 4. 根据日志调整参数优化效果 |
|
|
| ### 注意事项 |
|
|
| 1. **API 密钥** |
| - 确保配置了必要的 API 密钥 |
| - Tavily 用于搜索，Kaggle 用于下载 Kaggle 数据集 |
|
|
| 2. **网络环境** |
| - 如果在国内，建议使用 HuggingFace 镜像 |
| - 调整并行数量以适应网络带宽 |
|
|
| 3. **存储空间** |
| - 确保有足够的磁盘空间 |
| - 大型数据集可能需要数 GB 空间 |
|
|
| 4. **执行时间** |
| - 采集过程可能需要较长时间（几分钟到几小时） |
| - 可以通过限制下载任务数量来控制时间 |
|
|
| 5. **数据质量** |
| - 启用 RAG 增强可以提高数据质量 |
| - 调整采样参数以平衡质量和速度 |
|
|
| --- |
|
|
| ## 常见问题 |
|
|
| ### Q1: API 密钥如何获取？ |
| - **OpenAI/GPT**: 访问 [OpenAI Platform](https://platform.openai.com/) |
| - **Tavily**: 访问 [Tavily](https://tavily.com/) |
| - **Kaggle**: 访问 [Kaggle Settings](https://www.kaggle.com/settings) |
|
|
| ### Q2: 如何选择合适的模型？ |
| - **快速原型**: `gpt-3.5-turbo`, `deepseek-chat` |
| - **高质量输出**: `gpt-4o`, `claude-3-opus` |
| - **中文优化**: `qwen-max`, `deepseek-chat` |
|
|
| ### Q3: Pipeline 执行失败怎么办？ |
| 1. 检查执行日志中的错误信息 |
| 2. 确认输入数据格式正确 |
| 3. 检查算子参数配置 |
| 4. 启用调试模式自动修复 |
| 5. 查看 Agent 结果了解详细错误 |
|
|
| ### Q4: 如何提高数据采集质量？ |
| 1. 使用更精确的目标描述 |
| 2. 启用 RAG 增强 |
| 3. 调整数据集大小范围 |
| 4. 增加采样记录数量 |
| 5. 使用更强大的 LLM 模型 |
|
|
| ### Q5: 生成的代码可以直接使用吗？ |
| - **管线推荐**: 可以直接运行，但建议先在测试数据上验证 |
| - **算子编写**: 建议先测试，必要时手动调整 |
| - **手动编排**: 生成的代码已经过测试，可以直接使用 |
| - **Prompt 模板**: 建议多轮优化后再用于生产环境 |
|
|
| --- |
|
|
| ## 下一步 |
|
|
| - 查看 [架构文档](guides/architecture.md) 了解系统设计 |
| - 查看 [算子编写指南](guides/operator_write.md) 学习自定义算子 |
| - 查看 [工作流编写教程](tutorials/workflow_write.md) 学习创建工作流 |
| - 访问 [项目介绍](guides/project_introduction.md) 了解更多功能 |
|
|
| --- |
|
|
| ## 技术支持 |
|
|
| 如有问题或建议，请： |
| - 提交 [GitHub Issue](https://github.com/OpenDCAI/Paper2Any/issues) |
| - 查看 [FAQ](faq.md) |
| - 参考 [贡献指南](contributing.md) |
|
|
| ## 附录：Agent 结构化输出（response_schema）配置说明 |
| |
| 在很多场景下，我们希望 Agent 不只是返回一段自由文本，而是返回**结构化的 JSON 结果**，方便后续程序消费。 |
| DataFlow-Agent 在 `BaseAgentConfig` 中内置了针对 JSON 解析的快捷配置字段： |
| |
| - `parser_type`: 解析器类型，默认为 `"json"` |
| - `response_schema`: 期望的返回结构定义（轻量级 JSON Schema） |
| - `response_schema_description`: 对该结构的中文/英文文字说明 |
| - `response_example`: 一份期望的 JSON 返回示例 |
| - `required_fields`: 必须出现的字段列表，用于约束模型输出 |
|
|
| 这些字段可以通过 `create_simple_agent` / `create_react_agent` 等便捷函数传入，也可以自行构造 `SimpleConfig` / `ReactConfig` 后再调用 `create_agent`。 |
|
|
| ### 1. 基本用法示例：简单模式 Agent |
|
|
| 下面的示例中，我们要求 Agent 返回包含 `code` 和 `files` 两个字段的 JSON，其中 `code` 是字符串，`files` 是字符串列表： |
|
|
| ```python |
| from dataflow_agent.agentroles import create_simple_agent |
| |
| agent = create_simple_agent( |
| "coder", |
| # 解析器类型设为 json（默认即为 json） |
| parser_type="json", |
| # 期望的返回结构（轻量 JSON Schema） |
| response_schema={ |
| "code": "string", |
| "files": ["string"], # 表示由字符串组成的列表 |
| "summary": "string", # 可选字段，用于描述本次修改 |
| }, |
| # 对 Schema 的自然语言说明，帮助模型理解每个字段含义 |
| response_schema_description=( |
| "请返回代码生成结果。" |
| "code 字段包含完整的代码内容；" |
| "files 是本次修改涉及到的文件路径列表；" |
| "summary 对主要改动进行简要说明。" |
| ), |
| # 一份期望的返回示例，模型会参考该结构生成 |
| response_example={ |
| "code": "# 写在这里的是完整的 Python 代码 ...", |
| "files": ["dataflow_agent/agentroles/__init__.py"], |
| "summary": "新增了 create_simple_agent 的使用示例。", |
| }, |
| # 必须出现的字段 |
| required_fields=["code", "files"], |
| ) |
| |
| # 后续在你的业务逻辑中，一般会以异步方式调用 agent： |
| # result = await agent.execute({"task": "请为我实现一个计算阶乘的函数"}) |
| # print(result["code"]) |
| # print(result["files"]) |
| ``` |
|
|
| 要点说明： |
|
|
| 1. **parser_type 建议为 `"json"`** |
| `response_schema*` 这一组字段是为 JSON 解析场景设计的。当 `parser_type="json"` 时，框架会根据这些配置构建 Prompt 与解析逻辑，尽量保证返回满足你指定的结构。 |
| |
| 2. **`response_schema` 是“轻量级 JSON Schema”** |
| - 推荐使用简单的类型标注，如： |
| - `"string"`, `"number"`, `"boolean"` 等 |
| - `["string"]` 表示“字符串列表” |
| - 也可以嵌套字典/列表描述更复杂结构 |
| - 不必完全遵循官方 JSON Schema 规范，保持可读性和易理解为主。 |
| |
| 3. **`response_schema_description` 与 `response_example` 用于“教模型”** |
| - `response_schema_description`: 用自然语言解释每个字段含义和要求； |
| - `response_example`: 给出一份“长得像最终结果”的 JSON 示例。 |
| 在实践中，这两项对提升结构化输出的稳定性非常有帮助。 |
|
|
| 4. **`required_fields` 指定“必填字段”** |
| - `required_fields=["code", "files"]` 表示：无论如何，这两个 key 必须出现在最终 JSON 中； |
| - 这可以配合 ReAct 模式/验证逻辑，用于在缺字段时触发重试或报错（具体行为取决于所用 Agent 策略和解析实现）。 |
| |
| ### 2. 在 ReAct 模式中使用 `response_schema` |
| |
| `create_react_agent` 同样支持以上字段，使用方式几乎一致，只是多了 ReAct 本身的重试与验证能力： |
| |
| ```python |
| from dataflow_agent.agentroles import create_react_agent |
| |
| agent = create_react_agent( |
| "planner", |
| max_retries=3, |
| parser_type="json", |
| response_schema={ |
| "plan": ["string"], # 分步计划，每一步是一句自然语言描述 |
| "risks": ["string"], # 可能的风险点 |
| }, |
| response_schema_description=( |
| "请返回本次任务的分步计划，以及可能的风险点列表。" |
| "plan 字段是按执行顺序排列的步骤列表，risks 列出需要注意的问题。" |
| ), |
| response_example={ |
| "plan": [ |
| "分析用户提供的数据源格式。", |
| "根据数据格式选择合适的预处理算子。", |
| "设计并生成完整的 DataFlow Pipeline 代码。" |
| ], |
| "risks": [ |
| "数据中可能包含脏数据，需要额外清洗步骤。", |
| "某些算子依赖的第三方库可能尚未安装。" |
| ] |
| }, |
| required_fields=["plan"], |
| ) |
| ``` |
| |
| 在这种模式下： |
| |
| - 如果模型第一次返回的 JSON 不满足要求（字段缺失/类型不符等）， |
| - 策略层可以结合验证器（`validators`）和重试机制，对结果进行检查并尝试修正， |
| - 从而提高结构化输出的可靠性。 |
| |
| ### 3. 直接使用配置类（进阶用法） |
| |
| 如果你希望显式构造配置对象，也可以直接使用 `SimpleConfig` / `ReactConfig` 等，然后调用 `create_agent`： |
| |
| ```python |
| from dataflow_agent.agentroles import ( |
| SimpleConfig, |
| create_agent, |
| ) |
| |
| config = SimpleConfig( |
| model_name="gpt-4o", |
| parser_type="json", |
| response_schema={ |
| "title": "string", |
| "outline": ["string"], |
| }, |
| response_schema_description="生成一篇技术文章的大纲。", |
| response_example={ |
| "title": "如何使用 DataFlow-Agent 构建智能数据处理管线", |
| "outline": [ |
| "项目背景介绍", |
| "核心概念与模块划分", |
| "实战示例：从原始数据到可复用算子", |
| ], |
| }, |
| required_fields=["title", "outline"], |
| ) |
| |
| agent = create_agent("writer", config=config) |
| |
| # result = await agent.execute({"topic": "DataFlow-Agent 使用实践"}) |
| # print(result["title"]) |
| # print(result["outline"]) |
| ``` |
| |
| 这种方式在以下场景比较适合： |
| |
| - 你已经有一套统一的配置管理/注入机制； |
| - 希望在不同 Agent 之间重用同一份结构化返回配置； |
| - 或者需要在运行时动态调整配置（模型、温度、schema 等）。 |
| |
